INFORMIX-4GL. Reference Manual Supplement. Version 6.0 September 1996 Part No

Transcription

1 INFORMIX-4GL Reference Manual Supplement Version 6.0 September 1996 Part No

2 Published by INFORMIX Press Informix Software, Inc Bohannon Drive Menlo Park, CA Copyright by Informix Software, Inc.; provided, portions may be copyright in third parties, as set forth in documentation. All rights reserved. The following are worldwide trademarks of Informix Software, Inc., or its subsidiaries, registered in the United States of America as indicated by, and in numerous other countries worldwide: INFORMIX ; NewEra ; ViewPoint ; C-ISAM ; INFORMIX -OnLine Dynamic Server ; SuperView (SuperView technology Patent Pending) The following are worldwide trademarks of the indicated owners or their subsidiaries, registered in the United States of America as indicated by, and in numerous other countries worldwide: Adobe Systems Incorporated: PostScript All other marks or symbols are registered trademarks or trademarks of their respective owners. ACKNOWLEDGMENTS Documentation Team: Shannon Ayres, Adam Barnett, Kaye Bonney, Katarina Stenstedt Contributors: Tony Chu, Jon Deitch, Alan Denney To the extent that this software allows the user to store, display, and otherwise manipulate various forms of data, including, without limitation, multimedia content such as photographs, movies, music and other binary large objects (blobs), use of any single blob may potentially infringe upon numerous different third-party intellectual and/or proprietary rights. It is the user's responsibility to avoid infringements of any such thirdparty rights. RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS Software and documentation acquired with US Government funds are provided with rights as follows: (1) if for civilian agency use, with Restricted Rights as defined in FAR ; (2) if for Dept. of Defense use, with rights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribed in DFAR Any whole or partial reproduction of software or documentation marked with this legend must reproduce the legend. ii INFORMIX-4GL Reference Manual Supplement

3 INFORMIX-4GL Reference Manual Supplement Table of Contents Introduction How to Use This Supplement How This Supplement Is Organized Using 6.0 4GL with Programs Written for Prior Releases of 4GL.. 4 Chapter 1 Chapter 2 Chapter 3 Installation and Migration Installation Recommendations Making 4GL Work with Your Database Server Environment Changes When Migrating to a New Server Upgrading Your Databases Summary of Enhancements Enhanced Statements CASE CONSTRUCT GLOBALS LOAD PROMPT UNLOAD New and Enhanced Environment Variables Error Messages Changes to the 4GL Programmer s Environment Changes to 4GL Internals SQL Statements That Cannot Be Prepared Using the 6.0 4GL Enhancements Managing Screen Interactions Managing Queries by Example Managing Screen Input Creating Menus Moving the Cursor Around a Form

4 Determining the Initial Values to Display in Fields Manipulating the Values in Screen Field Buffers Determining the Last Keystroke Determining When a User Enters a Value in a Field Defining Fields with the INVISIBLE and BLACK Attributes Querying Tables UNION and UNION ALL UNION ALL and SELECT DISTINCT (or SELECT UNIQUE) Using Variables as Identifiers Using the ANSI-Compliant Enhancements Specifying Lowercase User Names Using Cursors to Update Rows Determining a Statement That Returns No Rows Closing a Closed Cursor Avoiding the ANSI Reserved Words Using the upscol Utility Enhancements Support of VARCHAR, DATETIME, and INTERVAL Data Types 3-21 Support of Remote Databases Writing Reports Printing a NULL Character in a Report Guidelines on 4GL Report Writing Using the RETURN Statement in a Report Parameterless Reports Guidelines for Global Variable Usage Temporary Tables Created by Multipass Reports The Eight-Column Limit in the ORDER BY Clause Input Statements in Reports Handling 4GL Runtime Errors Errors and Inconsistencies in Previous Implementations Differences in Default Error Behavior and ANSI Compliance Changes to 4GL Error Handling Support for Nested and Recursive ICB Statements Early Exits from Nested and Recursive Operations Precedence and Associativity of 4GL Operators Using Segmented Form Fields with WORDWRAP WORDWRAP in REPORTS Left-justification of Numeric Form Fields Using New REPORT/RUN/OPTION Functionality New REPORT Functionality New RUN Functionality New OPTION Functionality RUN...RETURNING Clause New C Functions: popstring( ) and retstring( ) iv INFORMIX-4GL Reference Manual Supplement

5 Chapter 4 Chapter 5 Chapter 6 The 4GL Compiler Environment Variables C4GLFLAGS and FGLPCFLAGS C4GLNOPARAMCHK Changes to the I4GL and C4GL Compilation System The Five-Phase I4GL Compilation Process Shell Scripts for Backward Compatibility The New -phase Option The New -keep and -nokeep Options The INFORMIXC and CC Environment Variables The C4GLFLAGS Environment Variable I4GL Libraries and Header Files Have Been Moved Number of Lines and Compiling Using Source Code Debuggers with I4GL Programs Shared Libraries Using the Shared Library Facility GL Function Libraries ORD( ) CURSOR_NAME( ) Variables in Global Scope GL Statement Syntax CASE CONSTRUCT The BY NAME Keywords The ON Clause The FROM Clause The ATTRIBUTE Clause The HELP Clause The BEFORE CONSTRUCT Clause The AFTER CONSTRUCT Clause The BEFORE FIELD Clause The AFTER FIELD Clause The ON KEY Clause The NEXT FIELD Statement The CONTINUE CONSTRUCT Statement The EXIT CONSTRUCT Statement The END CONSTRUCT Statement AUTONEXT Ignored by CONSTRUCT Using WORDWRAP in CONSTRUCT Using Functions in a CONSTRUCT Statement Table of Contents v

6 Interrupts in a CONSTRUCT Statement Strings Produced by a CONSTRUCT Statement Behavior of CONSTRUCT and get_fldbuf() FOREACH GLOBALS Variables in Global Scope INPUT The BY NAME Clause The WITHOUT DEFAULTS Clause The FROM Clause The ATTRIBUTE Clause The HELP Clause The BEFORE INPUT Clause The AFTER INPUT Clause The BEFORE FIELD Clause The AFTER FIELD Clause The ON KEY Clause The NEXT FIELD Statement The CONTINUE INPUT Statement The EXIT INPUT Statement The END INPUT Statement WORDWRAP in INPUT AFTER INPUT Control Block Using Functions in an INPUT Statement Editing During an INPUT Statement Completing an INPUT Statement INPUT ARRAY The WITHOUT DEFAULTS Clause The FROM Clause The HELP Clause The ATTRIBUTE Clause The BEFORE INPUT Clause The BEFORE ROW Clause The BEFORE INSERT Clause The BEFORE DELETE Clause The AFTER INPUT Clause The AFTER ROW Clause The AFTER INSERT Clause The AFTER DELETE Clause The BEFORE FIELD Clause The AFTER FIELD Clause The ON KEY Clause The NEXT FIELD Statement The CONTINUE INPUT Statement vi INFORMIX-4GL Reference Manual Supplement

7 The EXIT INPUT Statement The END INPUT Statement AFTER INPUT Control Block Using Functions in an INPUT ARRAY Statement Positioning the Cursor and Scrolling Inserting and Deleting Rows Editing During an INPUT ARRAY Statement Completing an INPUT ARRAY Statement LOAD Statement Transaction Management MENU The BEFORE MENU Clause The COMMAND Clause The KEY Clause The HELP Statement The CONTINUE MENU Statement The EXIT MENU Statement The NEXT OPTION Statement The SHOW OPTION and HIDE OPTION Statements The END MENU Statement Choosing a Menu Option Using Variables in a MENU Statement Keys in a Command Key Clause MENU COMMAND KEY Conflicts PROMPT OPTIONS PROMPT LINE Default Behavior UNLOAD Chapter 7 Chapter 8 Environment Variables C4GLFLAGS and FGLPCFLAGS C4GLNOPARAMCHK DBESCWT FGLSKIPNXTPG INFORMIXDIR INFORMIXTERM IXOLDFLDSCOPE LINES and COLUMNS PROGRAM_DESIGN_DBS SUPOUTPIPEMSG Error Message Modifications New and Changed Error Messages Deleted Error Messages Index Table of Contents vii

8 viii INFORMIX-4GL Reference Manual Supplement

9 Introduction Introduction How to Use This Supplement How This Supplement Is Organized Using 6.0 4GL with Programs Written for Prior Releases of 4GL... 4

10 2 INFORMIX-4GL Reference Manual Supplement

11 This supplement describes INFORMIX-4GL enhancements and miscellaneous 4GL features that were not documented in the INFORMIX-4GL Reference Manual Version 6.0. It also provides more thorough detail on installation and configuration tasks. The information in this document supplements the information in the Release 6.0 4GL manual set; for complete coverage you should use this manual with the 6.0 manuals. Besides the Version 6.0 INFORMIX-4GL Reference and INFORMIX-4GL Concepts and Use, the complete 6.0 4GL documentation set now includes: INFORMIX-4GL Reference Manual Supplement Version 6.0 (this document) INFORMIX-4GL by Example This manual includes several annotated 4GL examples. Informix Guide to SQL: Reference Version 6.0 or 7.1, Informix Guide to SQL: Tutorial Version 6.0 or 7.1 and Informix Guide to SQL: Syntax Version 6.0 or 7.1 These manuals describe how to use SQL to manage and create Informix relational databases. How to Use This Supplement Use this supplement in conjunction with the 6.0 4GL manual set. For information about more recent enhancements, use this supplement. For general information on using 4GL, see the 6.0 manual set. If you are unsure where to find some information, begin with this supplement to ensure that you get the most current information. Introduction 3

12 How This Supplement Is Organized How This Supplement Is Organized The organization of this supplement is as follows: Installation and migration Summary of enhancements Using the 6.0 4GL enhancements The 4GL compiler 4GL function libraries 4GL statement syntax Using the environment variables Error message modifications Using 6.0 4GL with Programs Written for Prior Releases of 4GL To use programs written for previous releases of 4GL with the current release, you must perform the following steps: 1. If you are using the RDS Version of 4GL, remove any.4go and.4gi files. 2. If you are using the C Compiler Version of 4GL, remove any 4GL-generated.4ec,.ec, and.c files. (Do not remove any.ec or.c files that you have written.) 3. Recompile all your.4gl source files. 4. If you are linking any ESQL/C routines that you have written to use with your 4GL applications, recompile all the.ec or.c files. 5. Recompile any form files. 6. Recompile any message files with the mkmessage utility. 4 INFORMIX-4GL Reference Manual Supplement

13 Installation and Migration Chapter 1 Installation Recommendations Making 4GL Work with Your Database Server Environment Changes When Migrating to a New Server Using 4GL Version 6.0 with Versions 6.0 or 7.1 of INFORMIX-SE or INFORMIX-OnLine Upgrading Your Databases

14 1-2 INFORMIX-4GL Reference Manual Supplement

15 When you upgrade to INFORMIX-4GL Version 6.0 from an earlier version, you need to install your Informix products in the correct order. Make sure your newly upgraded software works with the versions of the software you have already installed. In some cases you might need to upgrade other Informix products to be compatible with 4GL Version 6.0. The topics addressed in the following sections are: installation recommendations. making 4GL work with your database server. upgrading your databases. Installation Recommendations You should install 4GL Version 6.0 in a new directory together with any of the other 6.0 versions of the 4GL product family, Version 6.0 of INFORMIX-SQL (if applicable), and compatible versions of one or more Informix server products (INFORMIX-SE or INFORMIX-OnLine Dynamic Server). You can also install compatible versions of other Informix tools, such as embedded language products (for example, INFORMIX-ESQL/C), in the same installation directory. If your database server products are not Version 6.0 or higher, you must upgrade them. As with prior releases, you must install 4GL Version 6.0 and the Version 6.0 or higher database server products in the same installation directory. 4GL Version 6.0 cannot work with Version 5.0 or older database server products. 4GL Version 6.0 is compatible with both INFORMIX-SE Version 6.0 and INFORMIX-OnLine Dynamic Server Version 6.0. You can install either or both of these server products in the same directory as your 4GL Version 6.0. Installation and Migration 1-3

16 Installation Recommendations 4GL Version 6.0 is also compatible with both INFORMIX-SE Version 7.1 or higher and INFORMIX-OnLine Dynamic Server Version 7.1 or higher. You can install either or both of these server products in the same directory as your 4GL Version 6.0. You cannot mix a 6.0 version of one server with a 7.1 or higher version of the other server in the same installation directory, however. As noted earlier, you should install your 6.0 products in a new INFORMIXDIR directory rather than add them to an existing INFORMIXDIR directory. Using a new directory is preferable to installing over older products because it minimizes compatibility conflicts and allows you to remove the old (and now redundant) INFORMIX product directory as a unit after thoroughly testing the new installation. You must install Informix products one at a time. First, copy the product media contents for the first product into the installation directory. Next, run the installation script for that product. If error messages appear, correct the errors and recopy from the installation media. When the installation is successful, a confirming message appears. Repeat this process with each Informix product. If an error occurs with a given media read or installation script run, you only need to recopy and reinstall that individual product. You must install products in a particular sequence, depending on the version of database server in use: If you are using Version 6.0 database server products, install 6.0 versions of INFORMIX-SQL and the 4GL product family last. Install your products in the following sequence: 1. Informix embedded languages, if applicable 2. NewEra family products, if applicable 3. SE Version 6.0 and/or OnLine Dynamic Server Version INFORMIX-SQL Version 6.0, if applicable 5. 4GL Version 6.0 product family members 1-4 INFORMIX-4GL Reference Manual Supplement

17 Making 4GL Work with Your Database Server If you are using Version 7.1 database server products, install 6.0 versions of INFORMIX-SQL and the 4GL product family before installing one or more servers. Install your products in the following sequence: 1. Version 6.0 Informix embedded language products, if applicable 2. NewEra family products, if applicable 3. INFORMIX-SQL Version 6.0, if applicable 4. 4GL Version 6.0 product family members 5. Version 7.1 Informix embedded language products, if applicable 6. SE version 7.1 and/or OnLine Dynamic Server Version 7.1 Making 4GL Work with Your Database Server The way that 4GL Version 6.0 selects the database server has significantly changed from earlier versions. Therefore, users making the transition to 4GL Version 6.0 need to be familiar with the configuration and migration tasks needed to create a working environment with the new servers. We strongly recommend that you read the background information on configuration and migration of your database server products in the corresponding server product manuals: SE users should read Chapter 1, Installation, and Chapter 6, Database Migration, in the INFORMIX-SE Administrator s Guide (Version 6.0 or 7.1, as applicable). OnLine users should read the chapters of the INFORMIX-OnLine Dynamic Server Migration Guide that pertain to their environment. Environment Changes When Migrating to a New Server This section explains the typical migration steps to follow. These steps depend primarily on the version of the database servers previously in use. Installation and Migration 1-5

18 Upgrading Your Databases Using 4GL Version 6.0 with Versions 6.0 or 7.1 of INFORMIX-SE or INFORMIX-OnLine If you were previously using a 6.0 or higher version server with 4GL Version 4.1, you were using either INFORMIX-NET or the INFORMIX Relay Module (sqlrm) to provide a compatible interface to the newer servers. The SQLEXEC environment variable was set to a full or relative pathname ending in sqlexec (if using INFORMIX-NET) or sqlrm (if using the Relay Module), and the INFORMIXSERVER variable was set to the desired server name. Additionally, if you were using the OnLine Dynamic Server locally, the ONCONFIG environment variable might have been set to the name of the configuration file that belongs to the desired OnLine server. After you install the new version of 4GL with your SE and/or OnLine servers, you need to change your environment variable settings as follows: The SQLEXEC environment variable no longer applies. Unset it in your environments (including any login and shell configuration scripts). The INFORMIXSERVER (and ONCONFIG, if applicable) environment variable does not change as a direct result of the 4GL upgrade. For information about INFORMIXSERVER and ONCONFIG, see INFORMIX-SQL Reference Version 6.0, Appendix B. Important: The specified OnLine server must be on-line and accepting connections in order for 4GL to create or access databases. Upgrading Your Databases Your old 4.1 or 5.0 databases are automatically updated when you first use them with the new 6.0 or 7.0 server product. Once your databases are updated, they are incompatible with older server utilities or older tools (except via the Relay Module locally or via INFORMIX-NET over a network). 1-6 INFORMIX-4GL Reference Manual Supplement

19 Summary of Enhancements Chapter 2 Enhanced Statements CASE CONSTRUCT GLOBALS LOAD PROMPT UNLOAD New and Enhanced Environment Variables Error Messages Changes to the 4GL Programmer s Environment Changes to 4GL Internals SQL Statements That Cannot Be Prepared

20 2-2 INFORMIX-4GL Reference Manual Supplement

21 This chapter summarizes the 4GL Release 6.0 enhancements. Complete information on these enhancements appears in subsequent chapters of this supplement. Enhanced Statements The following statements have been enhanced: CASE CONSTRUCT FOREACH GLOBAL VARIABLES INPUT INPUT ARRAY LOAD MENU PROMPT UNLOAD The following paragraphs briefly describe the enhancements to these statements. For complete information on these enhancements, see Chapter 6, 4GL Statement Syntax. CASE Both 4GL compilers (C4GL and FGLPC) accept CASE statements with WHEN clauses. For more information, see CASE on page 6-6. Summary of Enhancements 2-3

22 CONSTRUCT CONSTRUCT This statement now supports the following clauses and statements, giving you greater control over CONSTRUCT processing: BEFORE CONSTRUCT clause AFTER CONSTRUCT clause BEFORE FIELD clause AFTER FIELD clause ON KEY clause NEXT FIELD statement CONTINUE CONSTRUCT statement EXIT CONSTRUCT statement 4GL executes the statements in the BEFORE CONSTRUCT clause after first filling the fields listed in the CONSTRUCT statement with blanks and before the user can enter values into the form fields. When the user presses the Accept key, 4GL executes the statements in the AFTER CONSTRUCT clause before constructing the Boolean expression. 4GL executes the group of statements in a BEFORE FIELD clause when a user moves the cursor into the identified field. Similarly, 4GL executes the group of statements in the AFTER FIELD clause after the user moves the cursor out of the identified field. 4GL executes the group of statements in an ON KEY clause if the user presses one of the identified keys while performing the query-by-example. Use the NEXT FIELD statement to move the cursor to a particular field or to the NEXT or PREVIOUS form field. NEXT places the cursor in the next field as identified by the CONSTRUCT statement. PREVIOUS places the cursor in the previous field as identified by the CONSTRUCT statement. The CONTINUE CONSTRUCT statement skips all subsequent statements within the CONSTRUCT statement and returns the cursor to the screen form so that the user can enter more query-by-example values. The EXIT CONSTRUCT statement causes 4GL to skip all statements between the EXIT CONSTRUCT statement and the END CONSTRUCT statement and to create the character variable containing the Boolean expression. 2-4 INFORMIX-4GL Reference Manual Supplement

23 GLOBALS During CONSTRUCT, when you enter criteria into a field and are using the AUTONEXT attribute, if you key past the form field delimiter, the cursor does not enter the next field. The extra segments of a WORDWRAP field are not used during CONSTRUCT. Only the first segment and the overflow line are used. This should provide sufficient space for query input. Release 6.0 of 4GL also lets you specify a HELP message for the statement. For more information, see CONSTRUCT on page 6-9. GLOBALS The overview of GLOBALS in the INFORMIX-4GL Reference defines two forms of the GLOBALS statement: one defines variables, the other refers to the file where global variables are defined. This section describes how to eliminate the possibility of doubly defined variables. For more information, see GLOBALS on page LOAD Beginning with Version 6.01, you can do one of the following when the database has a transaction log: Run the LOAD as its own transaction, so that any error causes the entire LOAD statement to be automatically rolled back (implicit transaction). Run the LOAD within an explicit transaction, so that a data error merely stops the LOAD statement in place with the transaction still open. For more information, see LOAD Statement Transaction Management on page Summary of Enhancements 2-5

24 PROMPT PROMPT In current releases of 4GL, you need to ensure that the length of the display list for the PROMPT statement is smaller than the number of columns on the active window, in order to avoid a runtime error. For more information, see PROMPT on page UNLOAD The UNLOAD statement now supports host variables in the WHERE clause of the embedded SELECT query. For more information, see UNLOAD on page New and Enhanced Environment Variables The following environment variables are either new or enhanced in this version of 4GL: C4GLFLAGS and FGLPCFLAGS C4GLNOPARAMCHK DBESCWT FGLSKIPNXTPG INFORMIXFGLPCODESW IXOLDFLDSCOPE LINES and COLUMNS PROGRAM_DESIGN_DBS SUPOUTPIPEMSG INFORMIXDIR INFORMIXTERM For complete information on the new and enhanced environment variables, see Chapter 7, Environment Variables. 2-6 INFORMIX-4GL Reference Manual Supplement

25 Error Messages Error Messages In Release 6.0 of 4GL, several error messages have been added, updated, and deleted. For descriptions of the new and modified error messages and information on accessing the error message files, see Chapter 8, Error Message Modifications. Changes to the 4GL Programmer s Environment This release of 4GL increases uniformity and consistency between the Compiled-4GL Programmer s Environment (I4GL) and the Rapid Development System Programmer s Environment (R4GL). The I4GL and R4GL programs acknowledge the PROGRAM_DESIGN_DBS environment variable that lets the you choose where to store the program information. A Program Design database stores build dependencies for 4GL programs. By default, this information is stored in the syspgm4gl database. When you want to develop a program using I4GL or R4GL, the program searches for a Program Design database. If the program cannot find the database, it creates one for you. You can choose the name of the database. If the program information is part of your database, it is much easier to export and import the information using this version of 4GL rather than previous versions. In the earlier versions of 4GL, the Module/Modify option of I4GL and R4GL programs found files with long names, but it did not distinguish between names such as: a bcdefghijklmnopq.4gl a bcdefghijklmnopqrstuvwxyz.4gl Now the I4GL and the R4GL Program Design database schemas only allow 10 characters for the base filename (excluding the four-character.4gl extension). These names are the length that the traditional System V file system allows. The program code eliminates filenames of more than 10 characters (plus the.4gl extension) from the lists before displaying them. Summary of Enhancements 2-7

26 Changes to the 4GL Programmer s Environment Both the I4GL and R4GL programs have a Query-Language option that runs isql -q. If ISQL is not available, the code tries to run dbaccess -q instead, which is available as a tool with both SE and OnLine Dynamic Servers. In the earlier releases, if ISQL was not available, neither I4GL nor R4GL ran DBACCESS. There is no limit to the number of 4GL modules, libraries, global files, or objects you can include in your I4GL and R4GL programs because the size of the tables that hold the information dynamically increases. If you add several 4GL modules to a program, the size of the table that holds the names of the 4GL files increments dynamically by 25%. For example, if the original size of the table that holds the names of the 4GL files is 100 entries, the table grows by 25 entries every time it dynamically increases. If you want to add another 40 modules, you need to do so in two stages. You are allocated 25 entries each time. After you enter the names of the first 25 modules, press ESC to return to the menu. Then add the remaining 15 modules. The new R4GL environment recompiles all the non-global files when you update any global files, whereas in the earlier releases, the files that were recompiled depended on the order in which the server returned the data. Thus, if a global file was changed and recompiled, it forced all subsequent files to be recompiled, but it did not force prior files to be recompiled. Now every non-global object file is recompiled if any of the global source files is more recent than the object file. The older version of I4GL created the following tables: source4gl, sourceother, libraries, and opts within the syspgm4gl database. Similarly, the older version of R4GL added the following tables: global, runner, and otherobj as part of the syspgm4gl database. The new versions of I4GL and R4GL create Program Design databases that contain all the above specified tables. The new environments automatically upgrade the older I4GL databases so that they contain all seven tables. If you delete only the executable(.4ge), the newer version of I4GL links the existing.o files and creates the executable, whereas the older versions of I4GL recompiled all the source files and linked the newly created object files to create an executable. 2-8 INFORMIX-4GL Reference Manual Supplement

27 Changes to 4GL Internals Changes to 4GL Internals The following errors are eliminated in this release of 4GL: The 4GL program cannot allocate any more space for temporary string storage (-4518) String of length >512 cannot be returned from function calls (-4517) Thus, partially evaluated string expressions no longer foul up the program. You might eventually run out of memory instead, but the temporary string space (TSS) is recovered whenever you exit a function or at the completion of a statement with a USING clause or string concatenation operation, so the TSS does not now become continuously filled. The internal operation of the memory allocation system has been completely rewritten. Any code that relies on the function acdealloc() will fail because that function has been eliminated. Any code that relies on being able to access alloctab will fail, because that structure has also been eliminated. All such code was using undocumented and unsupported knowledge of the internals of I4GL. If necessary, you can supply a dummy version of acdealloc() that does nothing: acdealloc(){}. You must revise any code that accesses alloctab, but you should be able to convert those routines into dummies too. Any p-code 4GL programs get the benefit of the new TSS handling without recompilation, but you must relink custom runners and debuggers. Unless there is compiled 4GL code built into the runner, there is no need to recompile the component object modules. Any compiled I4GL program does not gain any benefit from the new TSS handling without relinking. If you simply relink the programs, they will run out of memory when the system declines to give them any more memory. If you completely recompile I4GL programs, they should not run out of memory unless you are doing a computation that uses up all the memory. Summary of Enhancements 2-9

28 Changes to 4GL Internals The following code demonstrates the removal of the limits imposed by error A program that uses up all the memory would almost certainly have to use a recursive function such as the Ackerman function, as in the following code. This code has a deliberate bug in it because it uses a string as the return value, whereas it should be DECIMAL(32,0) (effectively a giant INTEGER) to be consistent with the arguments. MAIN DEFINE i DECIMAL(32,0), j DECIMAL(32,0), a CHAR(60) LET i = 3 -- Be wary about increasing this LET j = 3 LET a = "Result of ACKERMAN(", i USING "&", ",", j USING "&", ") = ", Ackerman(i, j) END MAIN DISPLAY a CLIPPED FUNCTION Ackerman(m, n) DEFINE m DECIMAL(32,0), n DECIMAL(32,0), k CHAR(32) CASE WHEN (m = 0) LET k = n + 1 WHEN (n = 0) LET k = Ackerman(m - 1, 1) OTHERWISE LET k = Ackerman(m - 1, Ackerman(m, n - 1)) END CASE RETURN k END FUNCTION 2-10 INFORMIX-4GL Reference Manual Supplement

29 Changes to 4GL Internals This code demonstrates the removal of the limits imposed by error MAIN END MAIN CALL func1() FUNCTION func1() DEFINE str i CHAR(2048), SMALLINT LET str = "A" FOR i = 2 to 2048 LET str[i] = "A" END FOR LET str = func2(str) DISPLAY "String = ", str END FUNCTION FUNCTION func2(str) DEFINE str i CHAR(2048), SMALLINT DISPLAY "String = ", str CLIPPED LET str = "B" FOR i = 2 to 2048 LET str[i] = "B" END FOR RETURN str END FUNCTION Summary of Enhancements 2-11

30 SQL Statements That Cannot Be Prepared SQL Statements That Cannot Be Prepared You cannot prepare the following SQL statements because the servers do not understand these operations: LOAD UNLOAD CHECK TABLE REPAIR TABLE INFO OUTPUT 2-12 INFORMIX-4GL Reference Manual Supplement

31 Using the 6.0 4GL Enhancements Chapter 3 Managing Screen Interactions Managing Queries by Example Managing Screen Input Creating Menus Moving the Cursor Around a Form Determining the Initial Values to Display in Fields Manipulating the Values in Screen Field Buffers Determining the Last Keystroke Determining When a User Enters a Value in a Field Defining Fields with the INVISIBLE and BLACK Attributes The INVISIBLE Attribute Querying Tables UNION and UNION ALL UNION ALL and SELECT DISTINCT (or SELECT UNIQUE) Using Variables as Identifiers Using the ANSI-Compliant Enhancements Specifying Lowercase User Names Using Cursors to Update Rows Determining a Statement That Returns No Rows Closing a Closed Cursor Avoiding the ANSI Reserved Words Using the upscol Utility Enhancements Support of VARCHAR, DATETIME, and INTERVAL Data Types Support of Remote Databases

32 Writing Reports Printing a NULL Character in a Report Guidelines on 4GL Report Writing Using the RETURN Statement in a Report Parameterless Reports Guidelines for Global Variable Usage Temporary Tables Created by Multipass Reports The Eight-Column Limit in the ORDER BY Clause Input Statements in Reports Handling 4GL Runtime Errors Errors and Inconsistencies in Previous Implementations Differences in Default Error Behavior and ANSI Compliance Changes to 4GL Error Handling Support for Nested and Recursive ICB Statements Early Exits from Nested and Recursive Operations Notes on Nested and Recursive Operations Precedence and Associativity of 4GL Operators Using Segmented Form Fields with WORDWRAP WORDWRAP in REPORTS Left-justification of Numeric Form Fields Using New REPORT/RUN/OPTION Functionality New REPORT Functionality New RUN Functionality New OPTION Functionality FORM MODE and LINE MODE RUN...RETURNING Clause New C Functions: popstring( ) and retstring( ) INFORMIX-4GL Reference Manual Supplement

33 The 6.0 Release of INFORMIX-4GL offers a wide range of enhancements. This chapter describes how to use the enhancements. The material in this section builds on information that appears in the INFORMIX-4GL Concepts and Use Version 6.0 and INFORMIX-4GL Reference Version 6.0. This chapter is organized as follows: Managing screen interactions Querying tables Using variables as identifiers Using the ANSI-compliant enhancements Using the upscol utility enhancements Writing reports Handling 4GL runtime errors Support for nested and recursive ICB statements Using segmented form fields with WORDWRAP Using new REPORT/RUN/OPTION functionality New C functions, popstring() and retstring() Managing Screen Interactions A significant portion of most 4GL applications involves managing screen interactions with the users of the program. These applications often include one or more screen forms that allow users to perform common tasks such as retrieving database information, updating this information, and adding new information to the database. Using the 6.0 4GL Enhancements 3-3

34 Managing Queries by Example This section describes the 6.0 enhancements that affect the way you write 4GL programs that include screen forms. In particular, it explains the following: Managing queries by example Managing screen input Creating menus Moving the cursor around a form Determining the initial values to display in fields Manipulating the values in screen field buffers Determining the last keystroke Determining when a user enters a value in a field Defining fields with the INVISIBLE and BLACK attributes Note that 4GL requires that your screen be at least 6 lines by 30 columns. The maximum screen size 4GL allows is based on the limitations of your terminal, or 600 lines by 600 columns, whichever is smaller. Managing Queries by Example You can now include the following clauses and statements with the CONSTRUCT statement: BEFORE CONSTRUCT and AFTER CONSTRUCT clauses BEFORE FIELD and AFTER FIELD clauses ON KEY clause NEXT FIELD statement CONTINUE CONSTRUCT statement EXIT CONSTRUCT statement You can use these clauses and statements to monitor and structure the actions of users as they perform a query by example. Use the BEFORE CONSTRUCT clause to perform a series of actions before the user begins entering criteria into the screen fields. You can include any 4GL statement in this clause. You can then use the AFTER CONSTRUCT clause to perform a series of actions after the user finishes entering criteria into the screen fields and before 4GL constructs the Boolean expression. 3-4 INFORMIX-4GL Reference Manual Supplement

35 Managing Queries by Example To specify a series of actions to execute before or after the cursor is placed in one or more fields, you can use the BEFORE FIELD or AFTER FIELD clauses. You can include any 4GL statement in these clauses. Use the ON KEY clause to specify actions to take when the user presses certain function or control keys. You can include any 4GL statement in this clause. You can control the order in which the cursor moves to fields by including the NEXT FIELD statement. You can use the NEXT FIELD statement in any of the CONSTRUCT statement clauses, including the BEFORE CONSTRUCT, AFTER CONSTRUCT, BEFORE FIELD, AFTER FIELD, and ON KEY clause. You can use the CONTINUE CONSTRUCT statement to exit a BEFORE CONSTRUCT, AFTER CONSTRUCT, BEFORE FIELD, AFTER FIELD, or ON KEY clause and return the cursor to the form with the CONSTRUCT statement still in effect. For example, the following CONTINUE CONSTRUCT statement appears in an AFTER CONSTRUCT clause. If the user specifies N or n to the prompt, the cursor returns to the form: CONSTRUCT BY NAME query_1 ON customer.*... AFTER CONSTRUCT IF NOT field_touched(customer.*) THEN PROMPT "Do you really want to see ", "all customer rows? (y/n) " FOR CHAR answer IF answer MATCHES "[Nn]" THEN MESSAGE "Enter search criteria; ", "press ESC to begin search." CONTINUE CONSTRUCT END IF END IF END CONSTRUCT Use the EXIT CONSTRUCT statement to terminate the CONSTRUCT statement. 4GL skips all the statements between the EXIT CONSTRUCT statement and the END CONSTRUCT statement. For more information about the CONSTRUCT statement, see CONSTRUCT on page 6-9. Using the 6.0 4GL Enhancements 3-5

36 Managing Screen Input Managing Screen Input You can now specify BEFORE INPUT and AFTER INPUT clauses and NEXT FIELD and CONTINUE INPUT statements within INPUT and INPUT ARRAY statements. These clauses and statements give you more flexibility when developing programs that use forms for entering information. Use the BEFORE INPUT clause to perform processing before the user enters values into fields in the form. You can include any 4GL statement in this clause. You can then use the AFTER INPUT clause to process the entered values when the user finishes with the form. While the user is entering information into the form, you can control the order in which the cursor moves to fields by specifying the NEXT FIELD statement. You can include the NEXT FIELD statement in any of the INPUT statement clauses. For example, the following INPUT statement specifies an ON KEY clause. If the user presses CTRL-B while in either of the specified fields, 4GL calls the stock_help( ) function and then places the cursor in the quantity field: INPUT ARRAY p_items FROM s_items.*... ON KEY (CONTROL-B) IF infield(stock_num) OR infield(manu_code) THEN CALL stock_help() NEXT FIELD quantity END IF... END INPUT Finally, you can use the CONTINUE INPUT statement to exit a BEFORE INPUT, AFTER INPUT, BEFORE FIELD, AFTER FIELD, or ON KEY clause and to return the cursor to the form. 3-6 INFORMIX-4GL Reference Manual Supplement

37 Creating Menus Creating Menus You can now identify menu names and menu-option names by using character variables or character strings. Also, you no longer need to confine your choice of menu-option names to those that begin with unique letters, nor must the menu appear at the top of the window. In addition, you can write a MENU statement that dynamically shows and hides menu options. Your program can include a single MENU statement that produces custom menus for different users. This means that you need not prepare and maintain a series of parallel MENU statements; you can use conditional logic to specify which options (and which forms) appear for each user. The following example demonstrates the use of the SHOW OPTION and HIDE OPTION statements in a MENU statement. The Long_menu option shows all options; the Short_menu option shows only the Query, Details, Long_menu, and Exit options. The example also demonstrates using a character variable to identify the menu name. DEFINE menu_name CHAR(20)... LET menu_name = "Order Management"... MENU menu_name COMMAND "Query" "Search for orders" CALL get_orders() COMMAND "Add" "Add a new order" CALL add_order() COMMAND "Update" "Update the current order" CALL upd_order() COMMAND "Delete" "Delete the current order" CALL del_order() COMMAND "Details" "Display details about the current order" CALL det_order() COMMAND "Long_menu" "Display all menu options" SHOW OPTION ALL COMMAND "Short_menu" "Display a short menu" HIDE OPTION ALL SHOW OPTION "Query", "Details", "Long_menu", "Exit" COMMAND "Exit" "Exit the Order Management Form" EXIT MENU END MENU Using the 6.0 4GL Enhancements 3-7

38 Moving the Cursor Around a Form Moving the Cursor Around a Form You can move a cursor around a form using the following keys: The RETURN and TAB keys The arrow keys The RETURN and TAB keys move the cursor among the fields in the default order. The default order for a CONSTRUCT or INPUT statement is determined by the order of the fields listed in the FROM clause or in the order implied by the column list in the ON clause. The default order for an INPUT ARRAY statement is the order in which the fields are displayed on the screen. The arrow keys work as follows: The up arrow [ ] key moves the cursor to the previous field. The down arrow [ ] key moves the cursor to the next field. The left arrow [ ] key moves the cursor one position to the left. It does not erase the contents of the field. The right arrow [ ] key moves the cursor one position to the right. It does not erase the contents of the field. You can alter the behavior of the up and down arrow keys by using the FIELD ORDER UNCONSTRAINED option of the OPTIONS statement. This option causes the up and down arrow keys to work as follows: The up arrow key moves the cursor to the nearest field above the current position of the cursor. The down arrow key moves the cursor to the nearest field below the current position of the cursor. 3-8 INFORMIX-4GL Reference Manual Supplement

39 Determining the Initial Values to Display in Fields Determining the Initial Values to Display in Fields When using the CONSTRUCT, INPUT, and INPUT ARRAY statements, you can control the values displayed in fields when 4GL initially displays the form. By default, the CONSTRUCT statement displays blanks and the INPUT and INPUT ARRAY statements display the default values of the fields. You can override this behavior by including: 1. a WITHOUT DEFAULTS clause, if you are using the INPUT or INPUT ARRAY statement. 2. a BEFORE CONSTRUCT or BEFORE INPUT clause. Within this clause, include: LET statements that assign values to the variables. a DISPLAY statement to display the variables. For example, the following INPUT statement assigns San Francisco to the p_customer.city variable and then displays the value on the screen form: INPUT BY NAME p_customer.fname THRU p_customer.phone WITHOUT DEFAULTS BEFORE INPUT LET p_customer.city = "San Francisco" DISPLAY BY NAME p_customer.city END INPUT Using the 6.0 4GL Enhancements 3-9

40 Manipulating the Values in Screen Field Buffers Manipulating the Values in Screen Field Buffers To validate, save, or alter the values of the screen field buffers, use the get_fldbuf( ) function. This function returns the character value of the field buffer value. For example, in the following program segment, the get_fldbuf( ) function obtains the value that the user enters in the lname field when the user presses CTRL-P. It then creates a query based on the value that the user entered in the lname field and displays an array of names beginning with the value entered in the lname field: DEFINE lname, myquery, partial_name CHAR(20), tw ARRAY[10] OF CHAR(20), a INT... INPUT BY NAME lname ON KEY (CONTROL-P) LET partial_name = get_fldbuf(lname) LET myquery = "select lname from teltab ", "where lname matches \"", partial_name CLIPPED, "*\"" OPEN WINDOW w1 AT 5,5 with form "tel_form" ATTRIBUTE (border) DISPLAY partial_name AT 1,1 PREPARE mysubquery FROM myquery DECLARE q1 CURSOR FOR mysubquery LET a = 0 FOREACH q1 INTO lname LET a= a END FOREACH DISPLAY a TO ncount IF (a = 0) THEN PROMPT "Nothing beginning with these letters" FOR CHAR partial_name ELSE IF (a > 10) THEN LET a = 10 END IF CALL set_count(a) DISPLAY ARRAY tw to srec.* END IF... END INPUT 3-10 INFORMIX-4GL Reference Manual Supplement

41 Determining the Last Keystroke Determining the Last Keystroke You can tell 4GL to perform tasks based on the last keystroke that the user entered on a form. 4GL compares the last keystroke that a user entered with one of the following values when you use the fgl_lastkey( ) and fgl_keyval( ) functions. ACCEPT AUTONEXT DELETE DOWN ESC ESCAPE HELP INSERT F1 through F64 INTERRUPT LEFT NEXTPAGE PREVPAGE RETURN RIGHT TAB UP CTRL-A through CTRL-Z a printable character For example, the following CONSTRUCT statement includes the fgl_lastkey( ) and fgl_keyval( ) functions in an AFTER FIELD clause. If the user presses the Accept key after entering a value in the fname field and has not entered a value in the lname field, 4GL displays a message telling the user to enter a last name and then places the cursor in the lname field: DEFINE key INT CONSTRUCT BY NAME query_1 ON customer.* AFTER FIELD fname IF field_touched(fname) THEN LET key = fgl_lastkey() IF key = fgl_keyval("accept") THEN IF NOT field_touched(customer.lname) THEN MESSAGE "You must enter a last name." NEXT FIELD lname END IF END IF END IF END CONSTRUCT Using the 6.0 4GL Enhancements 3-11

42 Determining When a User Enters a Value in a Field The field_touched( ) function is described in the following section. Determining When a User Enters a Value in a Field To determine if a user has entered a value in one or more fields, you can use the field_touched( ) function. This function determines if the user enters one of the following values in the specified fields: Any printable character CTRL-X CTRL-D The field_touched( ) function can appear anywhere within a CONSTRUCT, INPUT, or INPUT ARRAY statement except in the BEFORE CONSTRUCT or BEFORE INPUT clause. The following example checks if the user has entered a value into any form field: CONSTRUCT BY NAME query1 ON customer.*... AFTER CONSTRUCT IF NOT field_touched(customer.*) THEN PROMPT "Do you really want to see ", "all customer rows? (y/n)" FOR CHAR answer IF answer MATCHES "[Nn]" THEN CONTINUE CONSTRUCT END IF END IF END CONSTRUCT Defining Fields with the INVISIBLE and BLACK Attributes INVISIBLE and BLACK are not new attributes; however, the way in which 4GL displays these attributes has changed. If you define an input field as INVISIBLE, 4GL does not display the values a user enters. If you define a field as BLACK, 4GL displays the field in BLACK on a color terminal and in DIM on a monochrome terminal INFORMIX-4GL Reference Manual Supplement

43 Defining Fields with the INVISIBLE and BLACK Attributes As with all attributes, you set the INVISIBLE and BLACK attributes either in the ATTRIBUTES section of a form specification file or in the ATTRIBUTE clause of the following 4GL statements: CONSTRUCT DISPLAY DISPLAY ARRAY DISPLAY FORM ERROR INPUT INPUT ARRAY MESSAGE PROMPT OPEN WINDOW OPTIONS The INVISIBLE Attribute When you assign a field the INVISIBLE attribute, 4GL does not display the characters the user types in the field. However, the cursor moves through the field as the user types. You can specify the INVISIBLE attribute in the ATTRIBUTES section of a form specification file as shown in the following example: ATTRIBUTES... f005 = student.first_name; f006 = student.last_name; f007 = student.password, INVISIBLE; You can also assign the INVISIBLE attribute to 4GL statements that include an ATTRIBUTE clause. If you specify the INVISIBLE attribute for the following statements, 4GL does not display the text the user types: CONSTRUCT INPUT INPUT ARRAY OPTIONS (the INPUT or DISPLAY ATTRIBUTE clauses) PROMPT Using the 6.0 4GL Enhancements 3-13