================================================
                                RELEASE NOTES
                                     for
                           INFORMIX-NewEra 1.02.UC1
                                DATE: 03/11/96
                                    PART I
               ================================================


TABLE OF CONTENTS

   I.  SPECIAL NOTES FOR THIS RELEASE

  II.  OVERVIEW OF RELEASE NOTES

 III.  GUIDE TO DOCUMENTATION SET

  IV.  INSTALLATION INFORMATION

   V.  GENERAL INFORMATION AND CODING STANDARD TIPS
  VI.  CUSTOM AND ODBC-ENABLED RUNNERS AND DEBUGGERS
 VII.  WORKING WITH THE DEBUGGER

VIII.  WORKING WITH THE WINDOW PAINTER

  IX.  WORKING WITH THE CONNECTIVITY CLASS LIBRARY (CCL)
   X.  TROUBLESHOOTING INFORMATION
  XI.  MIGRATION ISSUES: CONVERTING LEGACY 4GL APPLICATIONS TO NEWERA

 XII.  INFORMIX CONNECTIVITY AND ENGINE ISSUES

XIII.  OUTSTANDING PRODUCT DEFICIENCIES
 XIV.  DEFECTS FIXED IN THIS RELEASE
  XV.  ENHANCEMENTS IN THIS RELEASE

I. SPECIAL NOTES FOR THIS RELEASE Upward Incompatibiltiy Issues Please note that, due to changes in the compiler for this release, all 4GL programs need to be recompiled before executing applications under this release. Please carefully review the notes for the fixes for Product Defects 37576 and 37962. The assignment of the status variable in 4GL has been changed, which may affect current NewEra applications. Previously in c-code with the WHENEVER ANY ERROR in effect, the status variable was not set after each statement. Now the status variable will be reset after each statement just as it is in p-code when the WHENEVER ANY ERROR is in effect. Additionally in p-code, statements which should cause the value of status to reset would not affect status when the statement and the check for status were embedded in a series of statements on a single line. This was erroneous behavior and needed to be fixed. However, this change may cause current applications to behave differently than they did before this release. Please review your 4GL code for multiple statements on a single line where the value of status is critical to your application. An example of this change is given in the discussion of the fix for Defect 37576.
II. OVERVIEW OF RELEASE NOTES The release notes contain information on changes from previous versions, known problems, and workarounds. They should be considered a supplement to Informix documentation. Problem IDs are assigned to known problems to assist you in identifying the problems to Client Services personnel. The purpose of these release notes is to make you aware of changes in products that might affect existing applications. 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.
III. GUIDE TO DOCUMENTATION SET See the documentation notes file, NEWERADOC_1.0, for more details concerning the documentation set and errata.
IV. INSTALLATION INFORMATION Getting Started The INFORMIX-NewEra Starts Here and Installation Guide contains instructions for installing the product, information on migrating a 4GL application to NewEra, an extensive glossary, and a comprehensive index of the documenta- tion. The NewEra Development System is used to create client applications or application servers that have GUI interfaces. The Development System distribution media contain four separate tarfiles. On CD-ROM systems, these files can be seen on the mounted CD-ROM device. The files have the following contents: newera.tar contains the basic INFORMIX-NewEra product, including GUI tools, compilers, runtime systems, and so forth. vppro.tar contains the INFORMIX-NewEra Viewpoint Pro product, which is used to create SuperView information for use by the Window Painter, and which can be used to create reports that are accessible through the ixReport class. odbc.tar contains the ODBC driver manager and ODBC drivers for database servers from Informix Software, Oracle, and Sybase. These drivers are used by the CCL/ODBC component of NewEra and their installation is optional, based on whether the user wishes to use the CCL/ODBC interface. se.tar contains a single-user INFORMIX-SE (Standard Engine) that can be installed if the user wishes to use a local SE for development purposes. The NewEra Application Server Development System is used to create application servers that have no GUI interface. The Application Server Development System distribution media contain four separate tarfiles. On CD-ROM systems, these files can be seen on the mounted CD-ROM device. The files have the following contents: nesvr.tar contains the basic INFORMIX-NewEra product, including GUI tools, compilers, runtime systems, and so forth, with the exception of the Window Painter, since the product is not intended for use in creating GUI interfaces. vprun.tar contains the INFORMIX-NewEra Viewpoint report runner, which is used to execute Viewpoint reports via the ixReport class. The Viewpoint reports can be created using either the Viewpoint Pro 2.1 development system that ships with the 2.00 Windows version of NewEra, or the reports can be created with NewEra Development System for Motif, which also includes Viewpoint Pro 2.1. odbc.tar contains the ODBC driver manager and ODBC drivers for database servers from Informix Software, Oracle, and Sybase. These drivers are used by the CCL/ODBC component of NewEra and their installation is optional, based on whether the user wishes to use the CCL/ODBC interface. se.tar contains a single-user INFORMIX-SE (Standard Engine) that can be installed if the user wishes to use a local SE for development purposes. The NewEra runtime system distribution can include up to four tarfiles, depending on the configuration purchased. On CD-ROM systems, these files can be seen on the mounted CD-ROM device. The files have the following contents: newerart.tar contains the basic INFORMIX-NewEra runtime distribu- tion required to support applications developed with NewEra. vprun.tar contains the NewEra report runner that allows users to execute reports created with INFORMIX-Viewpoint Pro and accessed through the ixReport class. odbc.tar contains the ODBC driver manager and ODBC drivers for database servers from Informix Software, Oracle, and Sybase. These drivers are only included if the user has purchased the ODBC option for the NewEra runtime. se.tar contains a single-user INFORMIX-SE (Standard Engine). It is included only if the user has purchased the SE option for the NewEra runtime. Users should note that only the files shipped as part of the NewEra distribu- tion media should be installed in the INFORMIXDIR containing NewEra. NewEra shares certain files, libraries, and executables with other Informix products, such as the INFORMIX-ESQL/C product and INFORMIX-SE, and these must all have consistent versions in order to avoid overwriting configurations files or shared libraries. The products shipped on the NewEra media are guaranteed to have consistent version numbers. Window Painter Requires NewEra ViewPoint Pro NewEra currently requires the NewEra ViewPoint Pro product for SuperView support. This product has been included as part of the distribution media for NewEra. NewEra ViewPoint Pro is also available as a standalone product. Supported Compilers To use the NewEra development tools, you must have the hardware vendor's C compiler installed on your system. Please refer to the Machine Specific Notes (NEWERAMACH_1.0) for specific Compiler version information. Terminals Informix has successfully performed tests with standard terminals supplied by the hardware vendors as well as NCD X-terms. NewEra has been tested using X-terminals containing 4 Mbytes of memory, but larger memory configurations may be required for very large applications. Be- cause the use of X-terminals or PC X-terminal emulators requires a large amount of network traffic between the X-terminal server and client, there may be significant performance degradation in GUI-intensive applications when using an X-terminal configuration, due to the overhead required for network traffic. Workstations and Servers In general, Informix does not advise the use of machine configurations that are not consistent with the hardware manufacturer's recommendations. In particular, the use of workstations as servers supporting multiple X-terminals used for NewEra development has been found to degrade the performance of the product, due to the fact that workstations are not configured for such a combination of tasks. If multiple developers are to use NewEra on a single server system, we advise the use of an appropriate server configuration. Such a configuration is, of course, dependent on the specific UNIX platform being used, but in general hardware manufacturers will specifically represent configurations as server configurations or workstation configurations. Conventional Memory Requirements A minimum of 32MB of conventional memory is recommended for development systems. 64MB is recommended for intensive development. Memory should be adjusted based on the number of users and the machine load. Swap Space Requirements Swap space requirements are based on the operating system. Please refer to the Machine Specific Notes (NEWERAMACH_1.0) for specific swap space recommendations. Disk Space Requirements INFORMIX-NewEra (newera.tar) requires 100MB disk space. INFORMIX- ViewPoint Pro (vppro.tar) requires 24MB of disk space.
V. GENERAL INFORMATION AND CODING STANDARD TIPS Pathnames When Converting from DOS/Windows If your existing DOS-developed INFORMIX-4GL or NewEra application uses full (absolute) pathnames, you will need to convert them from DOS to UNIX format. A sample conversion is shown below: DOS: C:\HOME\INFORMIX\ABCDEFGH.IJK UNIX: /home/informix/abcdefgh.ijk Note that because backslash (\) is the NewEra escape character, NewEra statements in a DOS format specify a double backslash (\\) wherever a single backslash is required in a pathname. There is no similar restriction in UNIX. Note also that if you have existing NewEra Application Builder projects developed on Windows, you will need to convert the project working directories to UNIX format as well if you plan to reference any sources using the Application Builder on UNIX. DELIMIDENT Environment Variables and INFORMIX-Online Dynamic Online ServerVersions 7.x Warning: Release 7.0 and later of Informix servers support the DELIMIDENT environment variable, which can extend the character set of SQL identifiers. NewEra cannot reference the names of database entities that use DELIMIDENT to include non-alphanumeric characters outside the character set of NewEra. Cursor Name Length Limitations Some cursor names (and the names of prepared objects) cannot have the usual 18 character length common to most SQL identifiers on Informix servers. NewEra now compiles .ec files to .cc files using the INFORMIX-ESQL/C version 7.10 compiler with the -local flag. This flag means that the scope of reference of the identifiers cursors, and statement identifiers of prepared statements is restricted to the module in which they are declared or prepared, rather than global to the entire NewEra program. Unless you use the -global flag to compile your program, the name of a cursor or statement identifier cannot be longer than nine characters, and must be unique among the names of cursors and prepared statements that are referenced in the same module. The internal cursor name is created by prepending the inode number of the file. This algorithm results in a limitation when using the -local flag: cursor names must be much shorter than the standard 18 characters. Estimates put the upper bound of cursor-id length at somewhere between 9 and 15 characters, depending upon the number of digits in the inode of the file in question. The result is that by default, NewEra cursor names that are more than nine characters long may generate ESQL/C warnings during the ESQL/C compilation phase. Furthermore, NewEra cursor names that are not unique within the first nine characters may generate fatal compilation errors during the ESQL/C compilation phase. For example, the cursor names below will undergo the indicated trans- formation and will no longer be unique within the file that has inode number 012345678: Cursor Name Modified Cursor Name ===================== ====================== lookmanohands 012345678lookmanohand lookmanohandcuffs 012345678lookmanohand Even if these cursor names are modified so that they are unique within the first nine characters, their length will generate ESQL/C warnings. Due to this limitation, application developers will en- counter the following situations: 1. Code that successfully completes the NewEra compilation stage may fail or get warnings during ESQL/C compilation. 2. Code that successfully compiles in one location may experience compilation failures when copied to another system or another location, since the inode numbers of the files change when copied. This limitation will be removed in a future release of NewEra. Linking Applications with Static vs. Dynamic Libraries Application developers can link their applications with NewEra libraries in two ways. The default is to link with dynamic libraries (shared objects). The 'Static Libraries' check box on Application Builder main screen, however, allows application developer to link their applications with a 'static version' of the NewEra libraries. The default, linking with dynamic libraries (shared objects), has the following advantages: * shared objects are shared by all the application that are linked with these libraries * resulting executables are smaller in size The disadvantages are * shared objects must be available at runtime If the user links his/her application with 'static version' of NewEra libraries then his/her application becomes a standalone application and does not require any libraries at run time. Developers should note that the application deployment version of INFORMIX-NewEra comes complete with all shared libraries required to support C-code or p-code applications, except for the C and Motif libraries supplied by the platform vendors and any libraries created by the application developer. NewEra Coding Standards Tips The following are the NewEra coding standards used by the Informix Technical Publications Department as they prepared the examples accessible through the Recipe Builder tool. These are tips and should not be considered final or all inclusive. They provide a good starting point for preparing your own coding standards. o When tabbing, use a tab stop of four (4) spaces. o Within class definitions, indent one tab for each statement block and align all member definitions. For example: CLASS of58 ... VARIABLE ... FUNCTION twit( twiddle, twaddle ) Note: The closing parenthesis must align with the beginning of the statement. o When continuing a statement onto subsequent lines, indent two tabs for the continued portion of the statement. This way lists, for example, can be distinguished from statement blocks: CLASS manuStockWin DERIVED FROM ixWindow FUNCTION manuStockWin( geometry ixGeometry : NEW ixGeometry ( Note that "geometry" is indented by two tabs from the beginning of the FUNCTION statement block. o When typing a long object expression that exceeds the end of the line, break the expression right after a period separator or an open parenthesis. For example, given the expression wind.getContainedObjByName("Retrieve", 1).disable( ) the following alternatives are acceptable: wind.getContainedObjByName("Retrieve", 1). disable( ) wind.getContainedObjByName( "Retrieve", 1 ).disable( ) o Named values including a default should be on separate lines, and the colon set off with surrounding spaces. For example: LET manu_code = NEW ixSuperField( colNum : 2, primaryKey : TRUE, ... ) o Use only one space between a variable's name and its type when defining the variable. o When defining a list of variables, use the keyword VARIABLE once followed by the list of variable definitions. For example: VARIABLE manuSt ixSuperTable, manu_name ixSuperField, All ixButton, errorString, stateString CHAR(30) o "Built-in" INFORMIX-4GL legacy constants, such as NULL and NOTFOUND, remain all upper case; NewEra constants are entered in mixed case as listed in the documentation. o Language keywords are upper case. o When naming graphical widgets, add to the name the following suffixes, depending on the widget type: Widget Suffix ------------- ------ Window WN Frame FR Button BT SuperTable ST SuperField SF PictureButton PB CheckBox CB RadioButton RB EditListBox EL ListBox LB Line LN Box BX Label LL TextBox TB Menu MN * PulldownMenu PM * CascadeMenu CM * MenuItem MI * o Do not attach the name of the base class to the name of the derived class. Filename Conventions-------------------- o Filenames *w.wif -- window module *w.4gl *w.4gh *l.4gl -- library module (general purpose functions) *l.4gh *m.4gl -- main module readme.txt -- extended text about the example MANIFEST -- a list of files belonging to the example *.mak -- a makefile for generating the executable
VI. CUSTOM AND ODBC-ENABLED RUNNERS AND DEBUGGERS Introduction ------------ This section describes the custom p-code interpreter (runner) and p-code debugger included with the 1.02.UC1 release of INFORMIX-NewEra. It also describes how to make a runner and/or debugger that is ODBC-enabled (that is, a runner or debugger that uses the CCL/ODBC interface rather than the CCL/Informix interface for its database access). A custom runner is a version of the p-code runner executable that has been linked by the application developer or end user. The purpose of the custom runner is to allow application developers to link their own C functions into the runner executable, so that these functions are callable from the NewEra program being interpreted by the runner. The C-code version of the NewEra product allows C functions to be directly linked into the final executable; such linking is not possible with p-code files, and so the C functions must be linked to the runner executable itself. The custom runner mechanism is also used to create an ODBC version of the p-code runner and/or debugger, by replacing the CCL/Informix library that is linked with the runner with the CCL/ODBC library. The NewEra Debugger is actually a specialized version of the p-code runner. Therefore, when an application developer wants to debug a p-code application that includes C functions, the developer must link a custom debugger that includes those functions. This section describes the way in which a user can link the custom runner and debugger, and describes the way in which C functions are called from NewEra language code. Creating a Custom Runner ------------------------ Custom runners are created using a shell script called cfglgo, which is located in the bin subdirectory of the INFORMIXDIR. This script is almost identical to the cfglgo script included with INFORMIX-4GL, so readers familiar with that script will find most of the description redundant. The syntax for cfglgo is: cfglgo [-n] [-odbc] [-static] [-Ldirectory] [-o name] [fgiusr] [usrfiles] This command line contains the following elements: cfglgo is the command that invokes the cfglgo shell script. -n prints the cc command generated by the shell script but suppresses execution of that command; this allows the user to preview the compilation and link command and is useful in debugging any problems encountered while creating a custom runner. -odbc is a flag that indicates that the CCL/ODBC rather than the CCL/Informix should be used for communication with the database server. -static is a flag indicating that the custom runner should be linked as a static executable, rather than the default behavior of linking all libraries as shared libraries. Note: Some UNIX system libraries may not be available in static form and will therefore be linked dynamically regardless of the -static flag. -Ldirectory is a flag indicating that the pathname given as directory should be included in the library search path; this allows users to inform the script of nonstandard locations for system libraries (e.g., Motif or C libraries). There may not be a space between -L and the directory name, since this parameter will be passed as a single unit to the C compiler and linker. Because the flag and directory are passed directly to the linker, this flag may vary between operating systems; users should consult the documentation for their C compiler to ensure that they are using the proper flag for the environment. -o name indicates that the custom runner executable produced by the script should be named . There must be a space between the flag and the name. If no output file name is specified, the name of the custom runner will be a.out; it is recommended that an output file name be provided, however, as a.out is a very common "junk" output file name and does not provide much information about the content or purpose of the file. fgiusr is the file containing the function declarations for all user-supplied C functions as well as the usrcfuncs structure. The file name for this file must end in the string fgiusr.c or fgiusr.o; it can be a full pathname. Only one fgiusr file can be linked into a custom runner or debugger. If the user does not supply one, the default $INFORMIXDIR/etc/fgiusr.c will be used. usrfiles are C source files, ESQL/C source files, compiled objects, and/or libraries that the application developer wishes to link into the custom runner. C source files are expected to end in .c, objects in .o, and ESQL/C files in .ec. Libraries should be specified using the full syntax -llib, where lib is the appropriate library abbreviation. (The flag used to specify a library abbreviation may be dependent on the operating system; users should employ the correct syntax for the linker on their system.) In addition to these command line arguments, the application developer may specify other options that are intended to be passed directly to the compiler or linker. These options vary from operating system to operating system. The order of the command line elements is important in the following ways: 1. If the -n flag is used, it should appear prior to any ESQL/C files on the command line, since the ESQL/C preprocessor is invoked immediately upon detection of a .ec file. If the -n flag does not appear on the command line first, the cfglgo script will actually perform the precompilation step rather than merely echoing the ESQL/C command line. 2. The name element must always follow the -o flag and must be separated from the -o flag by white space. 3. If the -L flag is used, it should be placed prior to any library names that will be affected by the flag. The cfglgo script permits multiple files to be linked into the custom runner. These files may be ESQL/C source files, C source files, or already-compiled object files. Creating a Custom Debugger -------------------------- Custom debuggers are created using a shell script called cfgldb, which is located in the bin subdirectory of the INFORMIXDIR. This script is derived from the cfglgo script, and is therefore almost identical in its usage. In general, an application developer should create a custom debugger using exactly the same cfgldb command line as the command line used to create the custom runner; that is, he or she should use the same command line options and link the same set of C functions for both cfglgo and cfgldb to ensure that he or she is debugging in the same environment that used for deployment. The syntax for cfgldb is: cfgldb [-n] [-odbc] [-static] [-Ldirectory] [-o name] [fgiusr] [usrfiles] This command line contains the following elements: cfgldb is the command that invokes the cfgldb shell script. -n prints the cc comand generated by the shell script but suppresses execution of that command; this allows the user to preview the compilation and link command and is useful in debugging any problems encountered while creating a custom debugger. -odbc is a flag that indicates that the CCL/ODBC rather than the CCL/Informix should be used for communication with the database server. -static is a flag indicating that the custom debugger should be linked as a static executable, rather than the default behavior of linking all libraries as shared libraries. Note: Some UNIX system libraries may not be available in static form and will therefore be linked dynamically regardless of the -static flag. -Ldirectory is a flag indicating that the pathname given as directory should be included in the library search path; this allows users to inform the script of nonstandard locations for system libraries (e.g., Motif or C libraries). There may not be a space between -L and the directory name, since this parameter will be passed as a single unit to the C compiler and linker. Because the flag and directory are passed directly to the linker, this flag may vary between operating systems; users should consult the documentation for their C compiler to ensure that they are using the proper flag for the environment. -o name indicates that the custom debugger executable produced by the the script should be named . There must be a space between the flag and the name. If no output file name is specified, the name of the custom debugger will be a.out; it is recommended that an output file name be provided, however, as a.out is a very common "junk" output file name and does not provide much information about the content or purpose of the file. fgiusr is the file containing the function declarations for all user-supplied C functions as well as the usrcfuncs structure. The file name for this file must end in the string fgiusr.c or fgiusr.o; it can be a full pathname. Only one fgiusr file can be linked into a custom runner or debugger. If the user does not supply one, the default $INFORMIXDIR/etc/fgiusr.c will be used. usrfiles are C source files, ESQL/C source files, compiled objects, and/or libraries that the application developer wishes to link into the custom debugger. C source files are expected to end in .c, objects in .o, and ESQL/C files in .ec. Libraries should be specified using the full syntax -llib, where lib is the appropriate library abbreviation. (The flag used to specify a library abbreviation may be dependent on the operating system; users should employ the correct syntax for the linker on their system.) In addition to these command line arguments, the application developer may specify other options that are intended to be passed directly to the compiler or linker. These options vary from operating system to operating system. The order of the command line elements is important in the following ways: 1. If the -n flag is used, it should appear prior to any ESQL/C files, since the ESQL/C preprocessor is invoked immediately upon detection of a .ec file. If the -n flag does not appear on the command line first, the cfgldb script will actually perform the precompilation step rather than merely echoing the ESQL/C command line. 2. The name element must always follow the -o flag and must be separated from the -o flag by white space. 3. If the -L flag is used, it should be placed prior to any library names that will be affected by the flag. The cfgldb script permits multiple files to be linked into the custom debugger. These files may be ESQL/C source files, C source files, or already-compiled object files. Using the C Interface --------------------- This section describes how the application developer can use C functions within the custom runner and debugger. The C interface used for NewEra is identical to that used by INFORMIX-4GL. Application developers should be aware that there is no interface that allows C functions to be called directly as member functions of NewEra objects, although a NewEra object may have a member function that in turn calls a C function. In order for the custom runner and/or debugger to be aware of the existence of C functions linked into the runner, the application developer must create a structure called usrcfuncs that is used to pass information about the C functions to the custom runner. (From this point on, "custom runner" will be used to refer both to the custom runner and the custom debugger.) This structure type is defined in $INFORMIXDIR/incl/fgicfunc.h and a sample source file that uses the structure type is located in $INFORMIXDIR/etc/fgiusr.c. A user should never alter the fgicfunc.h file or the fgiusr.c file.; any changes made to these files will result in malfunctions when using cfglgo and cfgldb to create custom runners or to create ODBC versions of the runner and debugger. The steps required in identifying C functions to the custom runner are: 1. The application developer must copy the file $INFORMIXDIR/etc/fgiusr.c to a working directory. 2. The application developer must then edit this file to include information about his C functions. 3. The application developer must then execute the cfglgo and/or cfgldb scripts to build a new runner or debugger with the C functions included. The process of editing the fgiusr.c file is relatively straightforward. The application developer must make the following additions: 1. Provide a function declaration or prototype for each of the user functions being linked to the runner as callable from NewEra source code. This can be done by using #include to include header files that perform the declarations or by putting declarations directly into the fgiusr.c file. The user should consult the C compiler documentation to ensure that he or she is are declaring functions appropriately for the specific C compiler. The functions must be declared before the statement that initializes the usrcfuncs structure. 2. Add a set of elements to the usrcfuncs structure for each function that must be recognized by NewEra applications. Each set of elements includes initializers for the function name (a character pointer), a pointer to the function itself, and an indication of the number of arguments expected by the function (an integer). The following is an example of an fgiusr.c source file that makes three functions known to the runner: calculate_trajectory(), get_telemetry(), and fire_retros(). /******************************************************************* ** ** FGIUSR.C ** *******************************************************************/ #include "fgicfunc.h" /* ** Declare all functions as type int. */ int calculate_trajectory(\x11int nargs\x11), get_telemetry(\x11int nargs\x11), fire_retros(\x11int nargs\x11); /* ** Put an entry into the usrcfuncs structure for each function. ** The number of parameters can be zero or more for functions that ** expect an exact number of arguments, or it can be less than zero ** if the function expects a variable number of arguments, where ** the negative number = (the maximum number of arguments that are ** expected)(-1). ** ** Note that the final three NULL or zero values must be the last ** set of initializers in the structure; they indicate that there ** are no more function table entries. */ cfunc_t usrcfuncs[] = { "calculate_trajectory", calculate_trajectory, 4, "get_telemetry", get_telemetry, 1, "fire_retros", fire_retros, -2, 0, 0, 0 } In the preceding example, calculate_trajectory() is a function that accepts exactly four arguments, get_telemetry() is a function that accepts exactly one argument, and fire_retros() is a function that accepts a variable number of arguments but no more than two. Note that the arguments themselves are not passed directly to the C functions; instead, NewEra passes the number of arguments directly to the C functions, which are then expected to get the arguments from the NewEra stack. The bodies of these functions can be included into the custom runner in the form of C source, object files, or libraries. These functions may in turn call other functions that are also linked into the runner but not identified in the usrcfuncs structure, which simply means that the unidentified function cannot be called directly from the NewEra application code. Once a custom runner or debugger has been created, the method of calling C functions linked into that custom runner or debugger is the same as the method of calling these functions from a compiled NewEra program. These methods of calling C function and passing arguments and return values between NewEra and C functions are documented in the INFORMIX-NewEra Language Reference in Appendix C. Creating ODBC-Enabled Runners and Debuggers ------------------------------------------- The NewEra product is not shipped with an ODBC-enabled runner or debugger, to avoid the unnecessary use of disk space for users who are not interested in deploying ODBC applications. ODBC-enabled versions of the runner and debugger are easily created with simple commands. A user or application developer who wishes to create an ODBC-enabled runner and/or debugger without adding any custom C code can do so merely by executing the cfglgo and/or cfgldb commands without specifying any user-written source or object files on the command line. The syntax is simply: cfglgo -odbc -o name cfgldb -odbc -o name where is the name of the new executable for the runner or de- bugger. (Obviously, they should not be given the same name.) One caution that should be observed: When creating an ODBC-enabled runner or debugger, the cfglgo and cfgldb scripts include the file $INFORMIXDIR/etc/fgiusr.c automatically. This file is provided as a template with NewEra and is shipped without any function pointers in the usrcfuncs structure. IF THIS FILE HAS BEEN REPLACED BY A FILE WITH FUNCTIONS IN THE usrcfuncs STRUCTURE, ERRORS MAY OCCUR BECAUSE THE FUNCTIONS WILL BE EXPECTED TO BE PRESENT AT RUNTIME. For this reason, users or developers should never edit the sample fgiusr.c file in the INFORMIXDIR, but should instead copy this file to a new name or location to add custom C functions. If a user or application developer wishes to create a runner or debugger which also contains user-written C functions or libraries, he or she should follow the instructions in the previous sections that describe how to create a custom runner or debugger. It should be noted that an application that is to be run with an ODBC-enabled runner should be debugged with an ODBC-enabled debugger.
VII. WORKING WITH THE DEBUGGER Interactive Debugger -------------------- Using the Debugger, you can run a program to completion, set and remove breakpoints, examine variables, find text in the source code area, and switch between modules. To caution you about the anomalies that might occur as you inspect your program in the Debugger, review the following issues. Custom Debugger --------------- Using a Unix script at a command line, you can create a custom Debugger that enables you to combine NewEra program modules with a C-Language module. This custom Debugger works through the NewEra Debugger user interface, enabling you to debug these special programs. Using the Debugger, you can inspect variables passed to and returned from C functions. However, you cannot view or step into the C functions called by your NewEra program, or inspect variables local to the C functions. For a complete description of the process of creating a custom debugger, see Section V ("CUSTOM AND ODBC-ENABLE RUNNERS AND DEBUGGERS"). Loading a Program into the Debugger ----------------------------------- As with the Interpreter, some programs may take longer to load into the Debugger than others. The Debugger window does not appear until your program has loaded. Running a Program in the Debugger --------------------------------- o If the Debugger quits unexpectedly, it may be due to Interpreter failures that cannot currently be caught by the Debugger. We recommend that you exit and then re-enter Motif. You can You can reload your program by clicking on the Debugger icon in the NewEra program group. o When a source module becomes inaccesible during a debugging session, such as from network disturbances or deletion of that source module, the program pointer may display erratic behavior. This behavior may also be present when you are stepping through INCLUDE statements within function, as well as some report statements. We recommend that you not code INCLUDE statements within functions. Instead, use the Debugger to inspect the included files separately. o When you exit the Debugger, a preference file called fgldb.prf is generated. This file stores the attributes of all windows generated by the Debugger. Window location and size are stored in this file, as well as any settings specified in the Find and Variable Inspector dialog boxes (the 20 most recently found strings or the 20 most recently inspected variables). Each time you exit the Debugger, the window attributes are retained. If you want the Debugger to display the default attributes of these windows, remove the fgldb.prf file before you launch the Debugger.
VIII. WORKING WITH THE WINDOW PAINTER This section describes the things you should be aware of when using Window Painter: 1. To allow the user more freedom, the Window Painter does not restrict you from doing some things that are logically not allowed. For example, you can change the name of a table in the Properties after pasting SuperFields in a SuperTable. This does not cause an error but it does result in an improper application. 2. The defaulting mechanism used for the appearance of objects like fonts and colors is as follows: An important feature of the Window Painter is the ability to compute default property values for the controls you paint so that you do not have to spend time setting each property individually. In general, a control inherits the appearance properties (font and color being two examples) of its container. SuperFields are an exception to this rule; since the NewEra extended catalogs may contain color and font information, this information is used to set the appearance of SuperFields. If there is no information in the extended catalogs, the appearance of a SuperField inherits from its container like any other control. Some primary considerations for the NewEra defaulting scheme are: o "Value inertia" -- an attribute value should not change unless the user explicitly makes it change. o The defaulting algorithm must be consistent -- the same defaulting scheme is used when dropping a new control, cutting/pasting, loading a WIF, etc. In particular, saving and reloading should not change the default values unless the database changed. o Pressing the default icon for a property that already has a default value should not change the value (unless the database has changed). With these considerations in mind, here is the defaulting algorithm for appearance (color and font) attributes: 1. Look for a value from the database (for SuperFields only). 2. Look for a local value in the control's container. 3. Look for a local value in the container's container. 4. Keep going up the container hierarchy until you come to the containing window. If a value has not been found yet, then use the appropriate system default for the control. System default values can be specific to the control. These defaults can be changed by users for their own desktop displays. If such user specified changes are not desired, default values should be avoided. If a container's appearance value gets changed, that change will get propagated down to all of its controls. This process includes propagation down to attributes of different names in some cases. For example, changing the foregroundColor of a frame will affect the foreColor attribute of a line or box control. In title_... attributes, (e.g. title_BackgroundColor) NewEra uses a modification to this algorithm: Use local value of title_BackgroundColor, if any. Otherwise, use local value of backgroundColor, if any. Otherwise, use the default value of the backgroundColor attribute using the defaulting algorithm listed above. There are two major exceptions to this defaulting algorithm. If you are painting a window in character mode, font attributes are fixed as fontName = Helvetica, fontSize = 10. Database default values are never checked in this case. Secondly, the Window Painter uses a 10-point Helvetica font as its default, and explicitly writes this font into applications rather than permitting applications to "pick up" user settings. This prevents users from overriding font informa- tion with fonts that create an unusable or visually unpleasant application. 3. If an error occurs while Window Painter is reading information from the database, an alert box appears. The text of the alert contains the database error number. You can obtain the description of the error using the "Informix Error Messages" in the on-line help system. 4. The following is a specification of how the NewEra Window Painter extracts data from the ViewPoint Pro extended catalog, and sets default values for SuperField and SuperTable properties. The Window Painter also extracts data from upscol. For completeness' sake, this document also specifies how Window Painter does that. Only default display rules in ViewPoint Pro are considered by the Window Painter. Conditional rules are expressly filtered out when querying syssvwformats and syscolformats. If the user explicitly changes a property value, or marks it as user-valued, then the defaulting rules described below no longer apply. The Window Painter leaves the value untouched. SuperField Properties: ID_HELPNUM syssvwinput/syscolinput.helpid ID_FONTNAME syssvwformats/syscolformats.typeface Note a value of "*" in syssvwformats.typeface indicates "transparency"; the Window Painter determines the value, rather than falling through to syscolformats. ID_FONTSIZE syssvwformats/syscolformats.fontsize Note a value of -1 in syssvwformats.fontsize indicates "transparency"; the Window Painter determines the value, rather than falling through to syscolformats. ID_FONTBOLD syssvwformats/syscolformats.fontstyle, Bit 0 Note a value of -1 in syssvwformats.fontstyle indicates "transparency"; the Window Painter determines the value, rather than falling through to syscolformats. ID_FONTITALIC syssvwformats/syscolformats.fontstyle, Bit 1 Note a value of -1 in syssvwformats.fontstyle indicates "transparency"; the Window Painter determines the value, rather than falling through to syscolformats. ID_FOREGROUNDCOLOR syssvwformats/syscolformats.fontcolor Note the color values stored in syssvwformats and syscolformats are in "BGR" format. The lowest 8 bits contain the red value, the next 8 bits contain the green value, and the next 8 bits contain the blue value. But VCL (and WIFL) expect colors to be in RGB format. So the Window Painter converts the color value to RGB format. If there no data is found in syssvwformats/syscolformats, then search in upscol: syscolatt.color Note that there are only seven color values allowed in upscol. Window Painter translates the colors as follows: UPSCOL VALUE COLOR NAME RGB VALUE (WIF) 0 White 16777215 1 Yellow 16776960 2 Magenta 16711935 3 Red 16711680 4 Cyan 65535 5 Green 65280 6 Blue 255 7 Black 0 ID_SHOWN syssvwaliases.colseq If -1, column is hidden ID_COLNUM User-specified, NOT defaulted from database Initially the order in which a SuperField is pasted into its SuperTable. The user can change the value through the Properties/ window. When the user changes colNum, the Window Painter limits the new value to be between 1 and the number of SuperFields in the SuperTable, and reorders the other SuperFields. ID_DATAJUSTIFY, ID_TITLEJUSTIFY syssvwformats/syscolformats.align "L" -> leftJustify "R" -> rightJustify "C" -> centerJustify "*" -> transparent value, see note below anything else -> leftJustify Note a value of "*" in syssvwformats.align indicates "transparency"; the Window Painter determines the value, rather than falling through to syscolformats. ID_INITIALDATAVALUE syssvwinput/syscolinput.attrval where attrname = "ENTRYDEF" Failing that search in upscol: syscolval.attrval where attrname = "ENTRYDEF" ID_INITIALQUERYVALUE syssvwinput/syscolinput.attrval where attrname = "QUERYDEF" Failing that search in upscol: syscolval.attrval where attrname = "QUERYDEF" ID_TITLE syssvwaliases/syscolumnext.title (gridform) syssvwaliases/syscolumnext.label (freeform) ID_MAXDATACHARS syssvwinput/syscolinput.attrval where attrname = "FIELDSIZE" Failing that search in upscol: syscolval.attrval where attrname = "FIELDSIZE" Failing that maxDataChars is computed based on syscolumns.type. Note: Window Painter updates maxDataChars if it is defaulted and the user changes the type of a SuperField. ID_PRIMARYKEY syssvwaliases.flag, Bit 0 (1 means primaryKey) When pasting SuperFields from an ordinary table (not a SuperView), the primaryKey is computed from data in sysconstraints and sysindexes. The SQL looks like this: SELECT constrtype, tabid, constrname, part1, part2,..., part8 FROM sysconstraints, sysindexes WHERE sysindexes.idxname = sysconstraints.idxname AND sysconstraint.tabid = AND syscontraints.constrtype = 'P' For each matching row of the join, we test whether, for the column in question, syscolumns.colno == absolute_value(sysconstraints.partN) where N = 1,2,...,8. If so, the column is a primary key. ID_SQLROLE syssvwinput/syscolinput.updateok y -> updateRole n -> noUpdateRole failing that, search upscol: syscolval.attrval where attrname = updateok if attrval = y then SQLRole = updateRole Currently, when the user sets the updateTable of a SuperTable, Window Painter automatically sets all of the SuperFields that belong to that table to have SQLRole = updateRole (except any SuperField whose type is SQLSerial). The information in ViewPoint Pro acts as a filter. That is, when the user selects the updateTable of a SuperTable, the SuperField's SQLRole is set to updateRole only if the SuperField belongs to the updateTable *and* syssvwinput/syscolinput.updateok = y. ID_DATASTATE syssvwinput/syscolinput.attrval where attrname = "NOENTRY" y -> disabledState n -> enabledState Failing that search in upscol: syscolval.attrval where attrname = "NOENTRY" y -> disabledState n -> enabledState ID_PICTURESTRING syssvwinput/syscolinput.attrval where attrname = picture Failing that search in upscol: syscolval.attrval where attrname = picture ID_FORMAT syssvwformats/syscolformats.format4gl Failing that search in upscol: syscolatt.def_format ID_SHIFTPOLICY syssvwinput/syscolinput.case Upper -> upShift Lower -> downShift Mixed -> noShift ID_REQUIRED syssvwinput/syscolinput.attrval where attrname = "REQUIRED" y -> True n -> False Failing that search in upscol: syscolval.attrval where attrname = "REQUIRED" y -> True n -> False ID_VERIFY syssvwinput/syscolinput.attrval where attrname = "VERIFY" y -> True n -> False Failing that search in upscol: syscolval.attrval where attrname = "VERIFY" y -> True n -> False ID_INCLUDETABLE syssvwinclude/syscolinclude Use only if there are no ranges specified For example, if any range field is 'Y', do not build includeTable. For every 'N' range, use extvalue to get the value. Presently the Window Painter doesn't support ranges in the include table. If the range field for any of the relevant rows is not 'N', then the row is ignored. ID_USEINCLUDES syssvwinput/syscolinput.attrval where attrname = "INCLUDEVAL" y -> True n -> False Failing that search in upscol: syscolval.attrval where attrname = "INCLUDEVAL" y -> True n -> False ID_AUTONEXTON syssvwinput/syscolinput.attrval where attrname = "AUTONEXT" y -> True n -> False Failing that search in upscol: syscolval.attrval where attrname = "AUTONEXT" y -> True n -> False SuperTable Properties: ID_MAXROWS syssvwauth.rowlimit select rowlimit from syssvwauth where svwid = If there is a global limit specified (syssvwauth.svwid = 0) and there is no limit specified for the SuperView in question, use the global limit. ID_SELECTFROMPART systables (Update as and when columns are pasted) This is a comma-separated list of tables used to construct the SQL SELECT statement for the SuperTable. The list of tables is determined by which tables the SuperTable's SuperFields come from. The Window Painter automatically maintains the list as the user adds/removes SuperFields to/from the SuperTable, as long as the property is in the "system-defined" state. If the user edits the field or marks it as user-defined, the Window Painter does not change the value. ID_SELECTJOINPART syssvwjoins (Update as & when columns are pasted) This is the join part of a SELECT statement, expressed as part of the WHERE clause, where two or more tables are joined through their primary/foreign key: SELECT from customer, orders, items WHERE customer.customer_num = orders.customer_num AND orders.order_num = items.order_num The Window Painter automatically computes the property if the SuperTable is connected with a SuperView. If the SuperTable is connected to ordinary table(s), this property is completely user-specified and defaults to NULL. For a SuperTable connected to a SuperView, the Window Painter maintains the property as the user adds/removes SuperFields to/from the SuperTable, as long as the property is in the "system-defined" state. If the user edits the field or simply marks it as user-defined, the Window Painter does not change the value. The ID_SELECTJOINPART property is a series of clauses separated by the keyword AND. Each clause is of the form: mastercol joinoperator detailcol1 The terms in the clause are obtained by querying syssvwjoins as follows: SELECT mastercol, joinoperator, detailcol1 FROM syssvwjoins WHERE svwid = AND tabalias = ID_SELECTORDERBYPART syssvworder The Window Painter automatically computes the property if the SuperTable is connected with a SuperView. If the SuperTable is connected to ordinary table(s), this property is completely user-specified and defaults to NULL. For a SuperTable connected to a SuperView, the Window Painter maintains the property as the user adds/removes SuperFields to/from the SuperTable, as long as the property is in the "system-defined" state. If the user edits the field or simply marks it as user-defined, the Window Painter does not change the value. The ID_SELECTORDERBYPART is a comma-separated list of column-name/sort-type pairs, obtained by querying syssvworder as follows: SELECT colalias, seqno, sorttype FROM syssvworder WHERE svwid = The Window Painter orders the returned the data by seqno, and builds a comma- separated list of "colalias sorttype" pairs. ID_SELECTFILTERPART This property is completely user-specified. ID_UPDATETABLE The Window Painter defaults ID_UPDATETABLE if the SuperTable contains SuperFields that are primary keys from one and only one database table. As the user pastes SuperFields into a SuperTable or cuts them from a SuperTable, the Window Painter must compute a list of candidate update tables (so that the user can choose the update table in the Property window). When the list contains only one item, then the Window Painter can default the ID_UPDATETABLE property to that one table. When ID_UPDATETABLE of a SuperTable is changed, the SQLRole of the SuperFields may be affected. If the superfield belongs to the new updateTable, and its datatype is not SQLSerial, and it is updateable (syssvwinput/syscolinput.updateok = y), and the current SQLRole is defaulted, then its SQLRole is set to updateRole. Conversely, if the SuperField does not belong to the new updateTable, and its SQLRole is defaulted, then SQLRole is reset to noUpdateRole. 5. Updateable property for a SuperTable will be derived as follows: - If the table has a primary key, the SQLRole property for a SuperField will be derived from SuperView/ Table properties from ViewPoint Pro if it is available. If not, the SQLRole property will be set to updateRole. SQLRole for the SQLSerial type will always be set to noUpdateRole. - If the table does not have a primary key, the user needs to set the primary key for SuperField and updateTable for SuperTable. When the updateTable property is set, SQLRole will be set to updateRole for SuperFields other than of type SQLSerial. 6. For SuperFields that represent a database column that is very long: For example, a column with a character datatype having a length of 30,000. The calculation from maxDataChars as explained above produces a width that overflows. To prevent this problem, the width of the SuperField is limited to a reasonable number of characters - 40, regardless of how large maxDataChars and encLength are. 7. A limit of 255 characters is placed on all edit boxes in the Window Painter GUI, except for the multiline edit boxes used in the Code window and the Menu Editor which are used to enter source code, are limited to 32500 characters. 8. Be aware that Window Painter reads the database only once. It reads it only when you choose your database for the first time in the properties. Using ViewPoint Pro to modify a table or SuperView defaults may have no effect on an already-running Window Painter session. Closing and restarting Window Painter will resolve the problem. Product Caveats for the Window Painter in version 1.02.UC1 1. If you want to load a .frm file, then you might face the following problems: - Sometimes more than one SuperTable is generated for a single .FRM file. This happens when you define a "screen record" in the INSTRUCTIONS section of your .per file. You can workaround this by deleting the extra SuperTable after loading the .frm file. It is important to be aware of the problem because the SuperTables appear directly on top of each other in the Window Painter and therefore the problem is not so easy to identify. Check the Properties window Control list to see which SuperTables exist and if there are too many. Alternatively, by moving a grid SuperTable in the canvas, you can detect the persence of the second SuperTable. - Note: If a field is specified in the "frm" file ATTRIBUTE section as a join of two columns, it will be created twice in the Window Painter, once for each column, resulting in visual overlaps. This is not a bug in the product though. - You might see some of the labels overlapping frame or other controls. You need to move these labels manually. - The form loader does its best to convert the defined attributes in the "frm" file into Window Painter equivalents. Below is a description of what is supported and how it is supported, and what is not supported. Form Loader Supported Attributes -------------------------------- AUTONEXT - Sets SuperField autoNextOn = True. DEFAULT - Data types SQLCHAR, SQLVCHAR, and SQLSMINT (smallint) are supported by setting initialDataValue. TODAY and CURRENT default values are not supported. In those cases, no initialDataValue will be set. DISPLAY LIKE - contains multiple parts DOWNSHIFT - Sets SuperField shiftPolicy = downShift for field. FORMAT - Sets SuperField format from per file. NOENTRY - Sets SuperField dataState = disabledState. PICTURE - Sets SuperField pictureString from per file. REQUIRED - Sets SuperField required = True. UPSHIFT - Sets Superfield shiftPolicy = upShift. VALIDATE LIKE - contains multiple parts VERIFY - Sets SuperField verify = True WORDWRAP - Sets SuperField multiline = True. Form Loader Unsupported Attributes ---------------------------------- COLOR COMMENTS DEFAULT - Data types not listed above INCLUDE REVERSE 2. There are several differences in the appearance of the controls you paint while running the Window Painter versus their appearance when your application is actually running. - At paint-time, the grid SuperTable does not have a horizontal scrollbar unless there are more columns in the SuperTable than will fit. At runtime, the scrollbar is always present, to facilitate you to increase the width of a column dynamically. - At paint-time, a vertical scrollbar is always present on the listbox control. At runtime, the scrollbar is present only if there are more items in the list than will fit in the box. - At paint-time, text entered in a textBox control does not get wrapped. (Note that the text is entered by using the Properties Window, not by direct type-in to the edit box. At paint-time, all the controls you paint are inactive.) At runtime, the text does wrap. 3. Ranges specified for superfields in a SuperView, SuperTable or form is not supported in this release. 4. If you are using JOIN in your SQL statement, you should fill the SelectJoinPart property for the SuperTable, if the SuperTable contains columns from more than one table. This property will not be filled in for you automatically.
IX. WORKING WITH THE CONNECTIVITY CLASS LIBRARY (CCL) Introduction These notes address known issues with version 1.02.UC1 of CCL and outline work-arounds for problems that might be encountered in deployment of NewEra applications in both an Informix and non-Informix engine environment. Planned Changes to the CCL in a future release of NewEra Currently all NewEra applications that use CCL/Informix create ixSQLConnect objects. For a future release of NewEra, these classes will be renamed to one of: ixSQLConnect ...base class ixSQLConnectESQL ...derived class Given the following declarations: VARIABLE connobj ixSQLConnect VARIABLE code INTEGER you can access constants in one of two ways -> -- Option A) LET connobj = NEW ixSQLConnect() LET code = connobj.SQL_Odbc_Sql_Conformance -- Option B) LET code = ixSQLConnect::SQL_Odbc_Sql_Conformance To minimize the impact of this class name change, option A is better. If option B is used, you will have to change every reference to the constant when the class name changes. For example, if you are using CCL/ODBC, the reference: ixSQLConnect::SQL_Odbc_Sql_Conformance would need to be changed to -> ixSQLConnectESQL::SQL_Odbc_Sql_Conformance The new CCL architecture will have these .4gh filenames: Class Header File ============= =========== ixSQLStmtESQL ixstmte.4gh isSQLConnESQL ixconne.4gh Though you can include ixstmt.4gh and ixconn.4gh in the UC1 release, we recommend that you use the new filenames as listed above, so you will not have to change them later. Using the ODBC Drivers When using the CCL/ODBC component, you should follow the guidelines below to prevent problems with the ODBC connection. 1. The Visigenic ODBC driver for the Oracle database specifically requires that applications be compiled and linked using the 3.0.1 version of the C compiler on the Solaris 2.4 platform. 2. The INFORMIXSERVER environment variable should always be set to point to a valid entry in a tbconfig or onconfig file when using the Informix version of the ODBC driver, regardless of whether or not the server is running locally. If you are running in client/server mode, you can simply copy the server's DBSERVERNAME entry to the client-side configuration file. 3. There is a known defect in the Sybase drivers concerning scalar values (see PART II of this document). 4. When executing a stored procedure against a Sybase server, you must use the full "EXECUTE " statement; the abbreviation "EXEC " will not work. 5. When using the Informix ODBC driver, the entry in the .odbc.ini file for the server should have a datasource name (section heading) that is the same as the database name for the connection to occur.
X. TROUBLESHOOTING INFORMATION The X11 Color Map When using a color terminal, users are restricted to the number of colors supported by the hardware (usually 256 colors). These colors are allocated and stored in the color map for the desktop. When using color-intensive graphical applications, the color map may be- come full. In the Window Painter, there is a known defect that causes some dialog boxes to display as black-on-black when this situation occurs. The workaround for this problem is to exit from color-intensive applications or remove color-intensive background images from the desktop, and then retry the Window Painter operation. In NewEra applications or in other NewEra tools, the visual interface is designed to recover as elegantly as possible from a full color map. The graphical rendering portion of the NewEra runtime detects that the color map is full when it attempts to allocate a new color for a widget and the allocation operation fails. First, NewEra scans the color map for a color that is close to the color being allocated ("close" meaning that the color difference is virtually indistinguishable to the human eye). Then, if there is no color within an acceptable range, NewEra automatically changes the widget's foreground and background colors to be the same as its parent window. Since the parent window must have managed to allocate colors, these colors are guaranteed to be available. As with the Window Painter, the user can dismiss color-intensive appli- cations or backgrounds that may be running on the same desktop in order to free the color map for the NewEra application. Newline Characters in Multi-line Text Boxes and SuperFields. UNIX (Motif) and Windows 3.1 use different definitions for newline characters. On UNIX platforms, placing a '\n' in a string is sufficient to force any text following it to be placed at the beginning of the next line. Windows 3.1, however, requires that the string contain "\r\n" to achieve the same effect. Since neither platform fully supports the other's newline conventions, odd visual behavior can occur when textual data created on one platform is displayed on another. If "\r\n" is part of a string on a UNIX platform, UNIX will add an "^M" to the end of the line and then generate a newline. If '\n' alone is part of a string on Windows, no newline will be generated, and either a "rectangle" character or no character will be displayed instead. Please note that although "\r\n" on Windows appears identical to '\n' on Motif, the '\r' is still a real character, and must be taken into account when calculating the length of a character string or comparing different strings. In NewEra there are three visual objects capable of displaying multi- line text. The first, ixLabel, can interpret a single '\n' as a newline on both platforms. Under Windows, it understands "\r\n" as well. Thus, maintaining platform independence with respect to ixLabel multi-line text is simple; just use '\n' in all cases. The other two visual objects, ixTextBox and ixSuperField, are more problematic. Since both are capable of receiving data from, as well as displaying data to, the end user, the GUI platform forces the controls to use the platform-specific newline conventions. This means some translation must occur before text entered on one platform can be displayed on another. Also note that, since '\r' is a real character, it does count against the maxChars limit. One recommended workaround for this problem is to maintain a platform-dependent header file which defines a constant representing the appropriate newline value. This constant can then be used in the rest of the application to handle newline characters. Additionally, many platforms provide utilities for converting between the Windows and UNIX formats. SunOS, for example, provides dos2unix and unix2dos for converting file formats. Problems When Using Various Editors Editing an empty ixByte (and now a NULL ixByte) can confuse some editors. This happens because many binary formatted files still require header information. Since binary editors deal with empty files differently than ASCII text editors, it is hard for us to know in advance how to deal with them too. For example, pbrush gives an error, but then creates a new bitmap... but not in the same file name that was passed in... which gives little chance for NewEra to read it back into the blob. Either way, the user should be aware of how their selected editor deals with empty files or they should write a script that checks for empty files and copies in correct formatted blank file into the passed file before calling the actual editor. Problems with Fonts in ViewPoint Pro vs. WindowPainter The font list generated by ViewPoint Pro is different from the WindowPainter font list. The list of fonts in WindowPainter is obtained from the Motif server at initialization time. Consequently, the WP uses the same fonts that are recognized by the NewEra runtime system. In contrast, the ViewPoint Pro product ships with its own set of fonts, so that it can provide WYSIWYG output of its forms and reports. Below is the list of ViewPoint Pro fonts. Of these, the ViewPoint Pro user should only select font names that are also present on the Motif server. If the user selects a ViewPoint Pro font which is not available to WindowPainter, then WindowPainter will ignore the ViewPoint Pro font name, and instead will by default use the font of the control's container. Viewpoint Pro Fonts -------------------- AvantGarde Bookman Courier Helvetica Helvetica-Narrow NewCenturySchlbk Palatino Symbol Times ZapfChancery ZapfDingbats Newerarc Updates Changes to $INFORMIXDIR/etc/newera/newerarc should be done carefully and only by the system administration as these changes will affect all users. Making changes in $HOME/.newerarc will only affect a single user. Application Builder - Problems Finding Database The Application Builder uses the name of the database as it was specified in the $INFORMIXDIR/etc/newera/newerarc file. If it cannot find it there, the name defaults to 'syspg4gl.' If it finds an older version of the database, it automatically upgrades it. If it cannot find one, it trys to create one according to ESQL/C network rules, which are as follows: * In the case of an SE, it will be created in the home directory. * In the case of OnLine engines, it will be created on the machine to which the user has his setnet pointing to. Application Builder - Customized Filters You can customize the filters in the program maintenance window by specifying the list in the $INFORMIXDIR/etc/newera/newerarc file as follows: Filters=*.4gl *.wif *.rc *.4gi *.4go *.c *.ec *.obj *.msg *.iem *.* This list must be separated only by spaces, no commas. Program-Build (make) Not Rebuilding Application "make" will only rebuild an executable (.exe or .4gi) if one of the component .4gl or .c files has been "touched". A source file is determined to have been "touched" if the date of the .4gl is later than the date of the corresponding .o or .4go file. Removing a source module from a program will NOT cause the program to be rebuilt. If you do wish to relink with the new program definition, you must delete or rename your old executable. This is standard "make" behavior. Refer to your "make" documentation for information on when a program is rebuilt. Tips for Problems with SuperTables o If you have an apply or a retrieve that doesn't seem to be working, check the return value from the apply or retrieve call. It returns a BOOLEAN that is usually ignored, but you can see if something failed by checking this value. o Check the contents of the actual generated SQL and to see why things aren't working. Put a call to one of the SQL build methods (buildSelectStr, buildInsertStr, etc), and DISPLAY the result, in the beforeRetrieve or beforeApply handler. This tells you what is being sent to the CCL. o Remember to specify a primary key if you are updating, and make sure the primary key is noUpdateRole. o Make sure you specify a joinPart if you are including SuperFields from more than one table. Canceling a Query Canceling the query itself: You can break out from an SQL request like a long query through the use of the ixSQLConnect Cancel Interface provided by CCL/Informix. Canceling the loading of a SuperTable with query data: You may need to find a way to interrupt a query periodically so your application can process cancel requests in the event queue. For example, before each row is fetched, execute a SLEEP 0. That interrupts the query and processes the next event, which may be the activate() event of your app's Cancel Query button. The handler for the cancel request can set the SuperTable's maxRows variable to the number that has already been fetched. No more rows are fetched, but you retain what you have already fetched.
XI. MIGRATION ISSUES: CONVERTING LEGACY 4GL APPLICATIONS TO NEWERA Please refer the Starts Here and Installation Guide for information on migrating legacy 4GL applications to NewEra.
XII. INFORMIX CONNECTIVITY AND ENGINE ISSUES Engines Supported NewEra 1.02.UC1 supports the following engines for development and runtime applications: INFORMIX-SE, versions 5.0x and 7.10 INFORMIX-OnLine, versions 5.0x and 7.10 INFORMIX-SE for NT, version 5.00 The 5.x engines are supported only in remote configurations. The 7.10 engines are supported in both local and remote configurations. You must have an INFORMIX database engine running to develop applications using your NewEra product, although you can use the CCL/ODBC interface to access Oracle and Sybase engines at runtime. The Oracle engine used to test ODBC interoperability was version 7.0.16.4.0, and the Sybase engine used was System 10.1. See the CCL/ODBC Reference for more information about using CCL/ODBC as as runtime database interface.
XIII. OUTSTANDING PRODUCT DEFICIENCIES Application Builder 37612 When using the Application Builder with a virtual window manager there are occasions when the compilation review window is displayed on the wrong segment of the virtual desktop. CCL/ODBC 38280 The Sybase driver returns the version of the database server in a noncompliant format. Compiler, Interpreter, and Runtime Execution 37860 The DBFORMAT environment variable is documented as overriding the behavior of DBMONEY under all situations. This is not universally true, and DBMONEY should be set to the same value as DBFORMAT in order to ensure consistent display of monetary values under all circumstances. 37970 Because the FUNCTION statement is treated as an executable statement for some purposes in the p-code version of the product, an application that uses an error-handling function identified in a WHENEVER state- ment should not rely on a test for the status immediately upon entering the function. For example, the following examples show examples of unreliable and reliable uses of the test for status: Unreliable Reliable ============================== ============================== FUNCTION errh() FUNCTION errh() IF ( status < 0 ) VARIABLE s INT = status ... IF ( s < 0 ) ... Debugger Help System 37059 The Motif version of the on-line help system, unlike the system on Microsoft Windows, is case-sensitive. On Windows, a search for information on the string "ixstring" will find references to the ixString class, while on Motif that search will fail. The use of case in class names and in the language syntax is consistent and predictable throughout the help system, which makes it easier to specify the correct syntax. Visual Classes 38517 An ixEditListBox with dropDown style cannot be scrolled using the down arrow key. Arrow key movement only works within the area visible to the user. 40388 Resizing the font of a multiline SuperField at runtime can cause the SuperField itself to resize. This problem can be avoided by setting the SuperField font at the time the interface is painted rather than setting the font size via calls to SuperField methods. Window Painter 33540 There are a couple of locations in the Window Painter where numeric values are not formatted according to the DBMONEY/DBFORMAT rules. These locations are hardcoded to display in US standard format (decimal point = period). 34042 A click within a Window Painter dialog box does not necessarily make the dialog box active. The user may have to click on a control within the dialog box or on the window decoration (e.g., border). 36355 When the Window Painter About box is closed by using the system menu, the Window Painter may hang. 36438 Context-sensitive help is not enabled in the Window Painter. In- stead of using the F1 key for help, users must choose Help from the Window Painter menu. 36569 The Window Painter hardcodes the database name in the generated code for ixSQLConnect::connect, based on the development-time database name. The generated code may need to be altered by hand-editing. 37034 When the color map of a color display device has been filled up, the Window Painter may display some of its dialog boxes as black-on- black, which makes them a difficult to use. The situation can be corrected by closing color-intensive applications that may be using up most of the slots in the X11 color map. 37186 When using OpenWindows on the Solaris 2.4 system, a quit from the File->Save menu occasionally results in a user error and unexpected termination of the Window Painter. 38378 When using the Window Painter for an extended period of time, the Properties and SuperTable Editor dialog boxes may suddenly "freeze" and refuse to process events. If this behavior occurs, the boxes can be unblocked by invoking any of the modal dialog boxes used by the Window Painter; it is recommended that at that point the user exit the Window Painter and restart it before continuing.
XIV. DEFECTS FIXED IN THIS RELEASE The following defects reported in 1.01.UD1 were fixed in the 1.02.UC1 release: Application Builder 43321 If a developer entered more than 20 characters in the "Libraries" field, only the first 20 characters were used in the makefile, and no warning was given about the truncation. This has been fixed so that the "Libraries" field now accepts up to 128 characters. CCL/ODBC 38459 If the user attempted to establish an ODBC connection with insufficient connection or login information, no modal dialog box requesting the missing information appeared. Now the dialog box is properly displayed. 38743 An unknown error number was being returned from calling getCancelText. It now returns the correct default message, "Cancel Current SQL Operation?". 43210 In a NewEra application that uses CCL/Informix directly, the following error message was displayed after a retrieve: -1263 A field in a datetime or interval is out of range or incorrect. This problem has been fixed so that no error is generated. 46764 NewEra windows that pass a username and a password to the ixConnect function now connect to the database successfully using the appropriate username/password combination. 48666 The Apply() function did not return an error when the SQL command executed by the function internally failed. Now, if the SQL command fails, the Apply function will now returns an error as expected. Compiler, Interpreter, and Runtime Execution 37576 The status variable in p-code was previously set on a line-by-line basis rather than a statement-by-statement basis. Therefore, given the following code, let a = b/0 let c = 1 if status < 0 the status variable would be less than 0 in older versions. The middle statement did not reset status as it should. This problem has been fixed so that executing the code above would give status a value of 0. 37962 When a WHENEVER ANY ERROR statement is in effect, the p-code version of the product resets the status variable after each statement and therefore status has to be checked immediately after each statement. C-code only set status when an error condition occurred, and that setting persisted despite the execution of subsequent successful statements. C-code now behaves the same way as p-code. 42761 FGLC previously ignored NULL values in AND and OR operations, making conditions ANDing and ORing NULL values evaluate incorrectly. The NULL values are now treated properly. 42991 Performing SetFormat on a datetime value no longer causes a core dump. 43412 When using the -clik option with c4gl, the macros generated were not enclosed by braces ({}) as they should be. Therefore, whenever a multi-line macro was expanded as part of an 'if' condition, only the first line was being conditionalized; the subsequent lines of the macro were not part of the condition. This problem has been fixed. Now the -clik option creates the macros enclosed in braces. 43697 When using the -c++ option with c4gl, NewEra was not locating the .cc file which is generated by using the -c++ switch. An error occurred during the compilation saying that the compiler cannot find the .c file. This error no longer occurs and the compilation is successful. 43429 A memory leak that was caused by executing SQL commands in 4GL code has been fixed. 45401 Having the environment variable DBNLS set to 2 and COLLCHAR set to 1 while compiling with fglpc caused the error "Compiler cannot continue." This problem has been resolved so that compilation is successful with the above environment variables set. 47636 When the Finish Report statement was omitted from a report program, a core dump would occur. This no longer causes a core dump. Visual Classes 37489 When creating buttons and setting one button as the default, the sizes of the buttons were slightly smaller at runtime than at paint time. This is because Motif puts a wide border around the default button and includes this border as part of the button's "real estate" on the screen. NewEra has been enhanced to accomodate Motif's borders so that default buttons are displayed at runtime the way they are displayed at paint time. 37897 Click events were not being executed as expected on rows not having focus of a grid form SuperTable. Now a single-click on a row not having focus invokes the Click event as it should. 41779 When the DBXEDIT variable was set and a report generated, the report was not displayed in the xterm window opened by DBXEDIT. Now it is displayed in the new xterm window in the editor as it should be. 42707 Previously, a SuperTable display did not refresh properly after an overlaying window had been closed. Now it refreshes properly. 42912 Previously, even if the Num Lock key was on, the user could not enter numerals into SuperFields using the numeric keypad. Now data can be entered into SuperFields using the numeric keypad when the Num Lock key is on. 45520 Tab key traversal had been generating extra focusout and focusin events. Now traversing with the tab key invokes only one focusout and focusin event for each object as expected. 45572 User-specified icons for ixWindow objects are now working properly. Before, the Informix default icon was always being displayed at runtime even though the user had specified a different one. 46884 Dynamically enabling and disabling menu items during runtime now works properly. 50418 International characters can now be entered into NewEra TextBoxes as expected. Window Painter 35465 The Alignment Types drop down list in the Alignment dialog box now closes as expected after a second Alignment type option is selected. 36451 The width of the drop down list for the Value EditListBox in the Properties dialog box has been standardized, so that the width does not change based on the property selected. 36914 Previously the SuperTable Editor would display names of table synonymns but would not display the columns of the synonym when selected. Now the columns of synonyms are displayed in the same manner that table columns are displayed. 37198 When a very large number of fields in a free form SuperTable painted on the Window Painter canvas was selected at once, they would unexpectedly shift horizontally and not always respond to an Undo. This problem has been fixed. 37216 An attempt to generate .4gl and .4gh files from a .wif file, using the iwp -b command will no longer fail when the .wif file is read-only. 37297 When compiling using iwp -b and with no database connect permission, the Window Painter now gives an appropriate error message instead of asking the user to enter a database name. 38147 The display of the rulers is now refreshed correctly when scrolling either vertically or horizontally within the Window Painter window. Previously, scrolling caused the ruler to look "broken." This is also known as Bug #36756. 38209 When opening a .wif file containing a single-line TextBox, the Window Painter gave the error: Slot HasHorizontalScrollBar cannot be changed while object is realized. This problem has been solved so that no error is displayed. 38380 A misleading error message was displayed when the user entered a value out of range for integer value properties. The error was Negative values not allowed for this property. The message now states: Value entered is not an integer or is out of range. 40855 Previously if a user opened the Save As dialog box and entered the name of an existing .wif file with the .wif extension, a confirmation dialog box would appear inquiring whether the user wants to overwrite the existing file. Yet if the user entered the name of an existing .wif file without the .wif extension, no confirmation dialog box appeared and the file was automatically overwritten. This has been changed so that in both cases mentioned above, the user gets the confirmation dialog box. 41310 In the Menu Editor, there were some problems getting the name of a menu item to be associated with the correct title of the menu item. These problems are now fixed so that there is no confusion in adding a new menu item and giving it a title and a name. 41851 The .wif files contained the wrong version number of the software. They now reflect the current version of the software. 42554 When saving a window to an existing .wif file after closing the window from the system menu, NewEra would abort. This problem has been fixed so that it behaves as expected. Debugger 41852 Pressing the Help button on the Debugger Launch window now gives help on the Debugger Launch window. It used to give help on the Application Launcher. XV. ENHANCEMENTS IN THIS RELEASE 46663 The startup time of windows containing SuperFields has been improved by as much as 50%.