reference manual supplement - pacs support · reference manual supplement version 6.0 september...

INFORMIX-4GL

Reference Manual Supplement

®

Version 6.0September 1996Part No. 000-7829

ii INFORMIX-4GL Refer

Published by INFORMIX Press Informix Software, Inc.4100 Bohannon DriveMenlo Park, CA 94025

Copyright 1981-1996 by Informix Software, Inc.; provided, portions may be copyright in third parties, as setforth in documentation. All rights reserved.

The following are worldwide trademarks of Informix Software, Inc., or its subsidiaries, registered in theUnited 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 theUnited 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 ofdata, including, without limitation, multimedia content such as photographs, movies, music and other binarylarge objects (blobs), use of any single blob may potentially infringe upon numerous different third-partyintellectual and/or proprietary rights. It is the user's responsibility to avoid infringements of any such third-party rights.

RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS

Software and documentation acquired with US Government funds are provided with rights as follows: (1) iffor civilian agency use, with Restricted Rights as defined in FAR 52.227-19; (2) if for Dept. of Defense use, withrights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribedin DFAR 227.7202. Any whole or partial reproduction of software or documentation marked with this legendmust reproduce the legend.

ence Manual Supplement

INFORMIX-4GL ReferenceManual Supplement

Table ofContents

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

Chapter 1 Installation and MigrationInstallation Recommendations . . . . . . . . . . . . . . 1-3Making 4GL Work with Your Database Server . . . . . . . . 1-5

Environment Changes When Migrating to a New Server . . . 1-5Upgrading Your Databases . . . . . . . . . . . . . . . 1-6

Chapter 2 Summary of EnhancementsEnhanced Statements . . . . . . . . . . . . . . . . . 2-3

CASE . . . . . . . . . . . . . . . . . . . . . 2-3CONSTRUCT . . . . . . . . . . . . . . . . . . 2-4GLOBALS . . . . . . . . . . . . . . . . . . . 2-5LOAD . . . . . . . . . . . . . . . . . . . . . 2-5PROMPT . . . . . . . . . . . . . . . . . . . . 2-6UNLOAD . . . . . . . . . . . . . . . . . . . 2-6

New and Enhanced Environment Variables . . . . . . . . . 2-6Error Messages . . . . . . . . . . . . . . . . . . . 2-7Changes to the 4GL Programmer’s Environment . . . . . . . 2-7Changes to 4GL Internals . . . . . . . . . . . . . . . . 2-9SQL Statements That Cannot Be Prepared . . . . . . . . . . 2-12

Chapter 3 Using the 6.0 4GL EnhancementsManaging Screen Interactions . . . . . . . . . . . . . . 3-3

Managing Queries by Example . . . . . . . . . . . . 3-4Managing Screen Input . . . . . . . . . . . . . . . 3-6Creating Menus . . . . . . . . . . . . . . . . . 3-7Moving the Cursor Around a Form . . . . . . . . . . . 3-8

iv INFOR

Determining the Initial Values to Display in Fields . . . . . 3-9Manipulating the Values in Screen Field Buffers . . . . . . 3-10Determining the Last Keystroke . . . . . . . . . . . 3-11Determining When a User Enters a Value in a Field . . . . . 3-12Defining Fields with the INVISIBLE and BLACK Attributes . . 3-12

Querying Tables . . . . . . . . . . . . . . . . . . 3-14UNION and UNION ALL. . . . . . . . . . . . . . 3-15UNION ALL and SELECT DISTINCT (or SELECT UNIQUE) . 3-16

Using Variables as Identifiers . . . . . . . . . . . . . . 3-17Using the ANSI-Compliant Enhancements . . . . . . . . . 3-17

Specifying Lowercase User Names. . . . . . . . . . . 3-18Using Cursors to Update Rows . . . . . . . . . . . . 3-18Determining a Statement That Returns No Rows . . . . . . 3-19Closing a Closed Cursor . . . . . . . . . . . . . . 3-19Avoiding the ANSI Reserved Words . . . . . . . . . . 3-20

Using the upscol Utility Enhancements . . . . . . . . . . 3-21Support of VARCHAR, DATETIME, and INTERVAL Data Types 3-21Support of Remote Databases . . . . . . . . . . . . 3-21

Writing Reports . . . . . . . . . . . . . . . . . . . 3-22Printing a NULL Character in a Report . . . . . . . . . 3-22Guidelines on 4GL Report Writing . . . . . . . . . . . 3-22Using the RETURN Statement in a Report . . . . . . . . 3-23Parameterless Reports . . . . . . . . . . . . . . . 3-23Guidelines for Global Variable Usage . . . . . . . . . . 3-24Temporary Tables Created by Multipass Reports . . . . . . 3-24The Eight-Column Limit in the ORDER BY Clause . . . . . 3-25Input Statements in Reports . . . . . . . . . . . . . 3-25

Handling 4GL Runtime Errors . . . . . . . . . . . . . 3-25Errors and Inconsistencies in Previous Implementations . . . 3-27Differences in Default Error Behavior and ANSI Compliance . 3-29Changes to 4GL Error Handling . . . . . . . . . . . 3-30

Support for Nested and Recursive ICB Statements . . . . . . . 3-30Early Exits from Nested and Recursive Operations . . . . . 3-35Precedence and Associativity of 4GL Operators . . . . . . 3-39

Using Segmented Form Fields with WORDWRAP . . . . . . 3-40WORDWRAP in REPORTS . . . . . . . . . . . . . 3-41Left-justification of Numeric Form Fields . . . . . . . . 3-42

Using New REPORT/RUN/OPTION Functionality . . . . . . 3-42New REPORT Functionality . . . . . . . . . . . . . 3-42New RUN Functionality . . . . . . . . . . . . . . 3-44New OPTION Functionality . . . . . . . . . . . . . 3-44RUN...RETURNING Clause . . . . . . . . . . . . . 3-45

New C Functions: popstring( ) and retstring( ) . . . . . . . . 3-46

MIX-4GL Reference Manual Supplement

Chapter 4 The 4GL CompilerEnvironment Variables . . . . . . . . . . . . . . . . . 4-3

C4GLFLAGS and FGLPCFLAGS . . . . . . . . . . . . 4-4C4GLNOPARAMCHK . . . . . . . . . . . . . . . 4-4

Changes to the I4GL and C4GL Compilation System . . . . . . 4-5 The Five-Phase I4GL Compilation Process . . . . . . . . 4-6Shell Scripts for Backward Compatibility . . . . . . . . . 4-7The New -phase Option . . . . . . . . . . . . . . . 4-8The New -keep and -nokeep Options . . . . . . . . . . 4-9The INFORMIXC and CC Environment Variables . . . . . . 4-11The C4GLFLAGS Environment Variable . . . . . . . . . 4-12I4GL Libraries and Header Files Have Been Moved . . . . . 4-12Number of Lines and Compiling . . . . . . . . . . . . 4-13

Using Source Code Debuggers with I4GL Programs . . . . . . 4-13Shared Libraries . . . . . . . . . . . . . . . . . . . 4-15

Using the Shared Library Facility. . . . . . . . . . . . 4-16

Chapter 5 4GL Function LibrariesORD( ) . . . . . . . . . . . . . . . . . . . . . . 5-4CURSOR_NAME( ) . . . . . . . . . . . . . . . . . . 5-5Variables in Global Scope . . . . . . . . . . . . . . . . 5-7

Chapter 6 4GL Statement SyntaxCASE . . . . . . . . . . . . . . . . . . . . . . . 6-6CONSTRUCT . . . . . . . . . . . . . . . . . . . . 6-9

The BY NAME Keywords . . . . . . . . . . . . . . 6-14The ON Clause . . . . . . . . . . . . . . . . . . 6-15The FROM Clause . . . . . . . . . . . . . . . . . 6-16The ATTRIBUTE Clause . . . . . . . . . . . . . . . 6-17The HELP Clause . . . . . . . . . . . . . . . . . 6-19The BEFORE CONSTRUCT Clause . . . . . . . . . . . 6-20The AFTER CONSTRUCT Clause . . . . . . . . . . . 6-20The BEFORE FIELD Clause. . . . . . . . . . . . . . 6-21The AFTER FIELD Clause . . . . . . . . . . . . . . 6-22The ON KEY Clause . . . . . . . . . . . . . . . . 6-22The NEXT FIELD Statement . . . . . . . . . . . . . 6-24The CONTINUE CONSTRUCT Statement . . . . . . . . 6-26The EXIT CONSTRUCT Statement . . . . . . . . . . . 6-27The END CONSTRUCT Statement . . . . . . . . . . . 6-27AUTONEXT Ignored by CONSTRUCT . . . . . . . . . 6-27Using WORDWRAP in CONSTRUCT . . . . . . . . . . 6-27Using Functions in a CONSTRUCT Statement . . . . . . . 6-33

Table of Contents v

vi INFOR

Interrupts in a CONSTRUCT Statement . . . . . . . . . 6-35Strings Produced by a CONSTRUCT Statement . . . . . . 6-35Behavior of CONSTRUCT and get_fldbuf(). . . . . . . . 6-36

FOREACH . . . . . . . . . . . . . . . . . . . . 6-40GLOBALS . . . . . . . . . . . . . . . . . . . . 6-44

Variables in Global Scope . . . . . . . . . . . . . . 6-45INPUT . . . . . . . . . . . . . . . . . . . . . . 6-46

The BY NAME Clause . . . . . . . . . . . . . . . 6-50The WITHOUT DEFAULTS Clause . . . . . . . . . . 6-51The FROM Clause . . . . . . . . . . . . . . . . 6-52The ATTRIBUTE Clause . . . . . . . . . . . . . . 6-52The HELP Clause . . . . . . . . . . . . . . . . 6-54The BEFORE INPUT Clause . . . . . . . . . . . . . 6-55The AFTER INPUT Clause . . . . . . . . . . . . . 6-55The BEFORE FIELD Clause . . . . . . . . . . . . . 6-56The AFTER FIELD Clause. . . . . . . . . . . . . . 6-57The ON KEY Clause. . . . . . . . . . . . . . . . 6-57The NEXT FIELD Statement . . . . . . . . . . . . . 6-59The CONTINUE INPUT Statement . . . . . . . . . . 6-60The EXIT INPUT Statement . . . . . . . . . . . . . 6-61The END INPUT Statement . . . . . . . . . . . . . 6-61WORDWRAP in INPUT . . . . . . . . . . . . . . 6-61AFTER INPUT Control Block . . . . . . . . . . . . 6-62Using Functions in an INPUT Statement. . . . . . . . . 6-62Editing During an INPUT Statement . . . . . . . . . . 6-65Completing an INPUT Statement . . . . . . . . . . . 6-65

INPUT ARRAY . . . . . . . . . . . . . . . . . . . 6-68The WITHOUT DEFAULTS Clause . . . . . . . . . . 6-73The FROM Clause . . . . . . . . . . . . . . . . 6-74The HELP Clause . . . . . . . . . . . . . . . . 6-74The ATTRIBUTE Clause . . . . . . . . . . . . . . 6-74The BEFORE INPUT Clause . . . . . . . . . . . . . 6-76The BEFORE ROW Clause . . . . . . . . . . . . . 6-77The BEFORE INSERT Clause. . . . . . . . . . . . . 6-77The BEFORE DELETE Clause . . . . . . . . . . . . 6-78The AFTER INPUT Clause . . . . . . . . . . . . . 6-78The AFTER ROW Clause . . . . . . . . . . . . . . 6-79The AFTER INSERT Clause . . . . . . . . . . . . . 6-79The AFTER DELETE Clause . . . . . . . . . . . . . 6-80The BEFORE FIELD Clause . . . . . . . . . . . . . 6-80The AFTER FIELD Clause. . . . . . . . . . . . . . 6-81The ON KEY Clause. . . . . . . . . . . . . . . . 6-82The NEXT FIELD Statement . . . . . . . . . . . . . 6-84The CONTINUE INPUT Statement . . . . . . . . . . 6-85


The EXIT INPUT Statement . . . . . . . . . . . . . 6-86The END INPUT Statement . . . . . . . . . . . . . 6-86AFTER INPUT Control Block . . . . . . . . . . . . . 6-86Using Functions in an INPUT ARRAY Statement . . . . . . 6-88Positioning the Cursor and Scrolling . . . . . . . . . . 6-90Inserting and Deleting Rows . . . . . . . . . . . . . 6-90Editing During an INPUT ARRAY Statement . . . . . . . 6-91Completing an INPUT ARRAY Statement. . . . . . . . . 6-91

LOAD Statement Transaction Management . . . . . . . . . 6-94MENU . . . . . . . . . . . . . . . . . . . . . . 6-98

The BEFORE MENU Clause . . . . . . . . . . . . . 6-102The COMMAND Clause . . . . . . . . . . . . . . 6-102The KEY Clause . . . . . . . . . . . . . . . . . 6-103The HELP Statement . . . . . . . . . . . . . . . . 6-103The CONTINUE MENU Statement . . . . . . . . . . . 6-103The EXIT MENU Statement . . . . . . . . . . . . . 6-104The NEXT OPTION Statement . . . . . . . . . . . . 6-104The SHOW OPTION and HIDE OPTION Statements. . . . . 6-105The END MENU Statement . . . . . . . . . . . . . 6-106Choosing a Menu Option . . . . . . . . . . . . . . 6-106Using Variables in a MENU Statement . . . . . . . . . . 6-108Keys in a Command Key Clause . . . . . . . . . . . . 6-111MENU COMMAND KEY Conflicts . . . . . . . . . . . 6-111

PROMPT . . . . . . . . . . . . . . . . . . . . . 6-113OPTIONS PROMPT LINE Default Behavior . . . . . . . . 6-113

UNLOAD . . . . . . . . . . . . . . . . . . . . . 6-115

Chapter 7 Environment VariablesC4GLFLAGS and FGLPCFLAGS . . . . . . . . . . . . . 7-4C4GLNOPARAMCHK . . . . . . . . . . . . . . . . . 7-5DBESCWT . . . . . . . . . . . . . . . . . . . . . 7-7FGLSKIPNXTPG . . . . . . . . . . . . . . . . . . . 7-8INFORMIXDIR . . . . . . . . . . . . . . . . . . . 7-8INFORMIXTERM . . . . . . . . . . . . . . . . . . 7-9IXOLDFLDSCOPE . . . . . . . . . . . . . . . . . . 7-10LINES and COLUMNS . . . . . . . . . . . . . . . . 7-12PROGRAM_DESIGN_DBS . . . . . . . . . . . . . . . 7-14SUPOUTPIPEMSG . . . . . . . . . . . . . . . . . . 7-15

Chapter 8 Error Message ModificationsNew and Changed Error Messages . . . . . . . . . . . . 8-3Deleted Error Messages . . . . . . . . . . . . . . . . 8-16

Index

Table of Contents vii

viii INFO
RMIX-4GL Reference Manual Supplement

Introduction

Introduction

How to Use This Supplement . . . . . . . . . . . . . . . 3

How This Supplement Is Organized . . . . . . . . . . . . . 4

Using 6.0 4GL with Programs Written for Prior Releases of 4GL . . . 4

2 INFOR

This supplement describes INFORMIX-4GL enhancements andmiscellaneous 4GL features that were not documented in the INFORMIX-4GLReference Manual Version 6.0. It also provides more thorough detail oninstallation and configuration tasks. The information in this documentsupplements the information in the Release 6.0 4GL manual set; for completecoverage you should use this manual with the 6.0 manuals.

Besides the Version 6.0 INFORMIX-4GL Reference and INFORMIX-4GLConcepts and Use, the complete 6.0 4GL documentation set now includes:

■ INFORMIX-4GL Reference Manual Supplement Version 6.0 (thisdocument)

■ INFORMIX-4GL by Example

This manual includes several annotated 4GL examples.

■ Informix Guide to SQL: Reference Version 6.0 or 7.1, Informix Guide toSQL: Tutorial Version 6.0 or 7.1 and Informix Guide to SQL: SyntaxVersion 6.0 or 7.1

These manuals describe how to use SQL to manage and createInformix relational databases.

How to Use This SupplementUse this supplement in conjunction with the 6.0 4GL manual set. For infor-mation about more recent enhancements, use this supplement. For generalinformation on using 4GL, see the 6.0 manual set. If you are unsure where tofind some information, begin with this supplement to ensure that you get themost current information.

Introduction 3

How This Supplement Is Organized

How This Supplement Is OrganizedThe 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 PriorReleases of 4GLTo 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 .4gifiles.

2. If you are using the C Compiler Version of 4GL, remove any4GL-generated .4ec, .ec, and .c files. (Do not remove any .ec or .c filesthat you have written.)

3. Recompile all your .4gl source files.

4. If you are linking any ESQL/C routines that you have written to usewith 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

1Chapter

Installation and Migration

Installation Recommendations . . . . . . . . . . . . . . . 1-3

Making 4GL Work with Your Database Server . . . . . . . . . 1-5Environment Changes When Migrating to a New Server . . . . 1-5

Using 4GL Version 6.0 with Versions 6.0or 7.1 of INFORMIX-SE or INFORMIX-OnLine . . . . 1-6

Upgrading Your Databases . . . . . . . . . . . . . . . . 1-6

1-2 INFO

hen you upgrade to INFORMIX-4GL Version 6.0 from an earlierversion, you need to install your Informix products in the correct order. Makesure your newly upgraded software works with the versions of the softwareyou have already installed. In some cases you might need to upgrade otherInformix 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 RecommendationsYou should install 4GL Version 6.0 in a new directory together with any of theother 6.0 versions of the 4GL product family, Version 6.0 of INFORMIX-SQL (ifapplicable), and compatible versions of one or more Informix server products(INFORMIX-SE or INFORMIX-OnLine Dynamic Server). You can also installcompatible versions of other Informix tools, such as embedded languageproducts (for example, INFORMIX-ESQL/C), in the same installationdirectory.

If your database server products are not Version 6.0 or higher, you mustupgrade them. As with prior releases, you must install 4GL Version 6.0 andthe Version 6.0 or higher database server products in the same installationdirectory. 4GL Version 6.0 cannot work with Version 5.0 or older databaseserver products.

4GL Version 6.0 is compatible with both INFORMIX-SE Version 6.0 andINFORMIX-OnLine Dynamic Server Version 6.0. You can install either or bothof these server products in the same directory as your 4GL Version 6.0.

W

Installation and Migration 1-3

Installation Recommendations

4GL Version 6.0 is also compatible with both INFORMIX-SE Version 7.1 orhigher and INFORMIX-OnLine Dynamic Server Version 7.1 or higher. You caninstall either or both of these server products in the same directory as your4GL Version 6.0. You cannot mix a 6.0 version of one server with a 7.1 orhigher version of the other server in the same installation directory, however.As noted earlier, you should install your 6.0 products in a new INFORMIXDIRdirectory rather than add them to an existing INFORMIXDIR directory.

Using a new directory is preferable to installing over older products becauseit minimizes compatibility conflicts and allows you to remove the old (andnow redundant) INFORMIX product directory as a unit after thoroughlytesting the new installation.

You must install Informix products one at a time. First, copy the productmedia contents for the first product into the installation directory. Next, runthe installation script for that product. If error messages appear, correct theerrors and recopy from the installation media. When the installation issuccessful, a confirming message appears.

Repeat this process with each Informix product. If an error occurs with agiven media read or installation script run, you only need to recopy andreinstall that individual product.

You must install products in a particular sequence, depending on the versionof database server in use:

■ If you are using Version 6.0 database server products, install 6.0versions of INFORMIX-SQL and the 4GL product family last. Installyour 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 6.0

4. INFORMIX-SQL Version 6.0, if applicable

5. 4GL Version 6.0 product family members

1-4 INFORMIX-4GL Reference Manual Supplement

Making 4GL Work with Your Database Server

■ If you are using Version 7.1 database server products, install 6.0versions of INFORMIX-SQL and the 4GL product family beforeinstalling one or more servers. Install your products in the followingsequence:

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 ServerThe way that 4GL Version 6.0 selects the database server has significantlychanged from earlier versions. Therefore, users making the transition to 4GLVersion 6.0 need to be familiar with the configuration and migration tasksneeded to create a working environment with the new servers. We stronglyrecommend that you read the background information on configuration andmigration of your database server products in the corresponding serverproduct 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-OnLineDynamic Server Migration Guide that pertain to their environment.

Environment Changes When Migrating to a New ServerThis section explains the typical migration steps to follow. These stepsdepend primarily on the version of the database servers previously in use.

Installation and Migration 1-5

Upgrading Your Databases

Using 4GL Version 6.0 with Versions 6.0 or 7.1 of INFORMIX-SE orINFORMIX-OnLine

If you were previously using a 6.0 or higher version server with 4GL Version4.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 pathnameending in sqlexec (if using INFORMIX-NET) or sqlrm (if using the RelayModule), and the INFORMIXSERVER variable was set to the desired servername. Additionally, if you were using the OnLine Dynamic Server locally, theONCONFIG environment variable might have been set to the name of theconfiguration 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 inyour environments (including any login and shell configurationscripts).

■ The INFORMIXSERVER (and ONCONFIG, if applicable)environment variable does not change as a direct result of the 4GLupgrade. For information about INFORMIXSERVER andONCONFIG, see INFORMIX-SQL Reference Version 6.0, Appendix B.

Important: The specified OnLine server must be on-line and accepting connectionsin order for 4GL to create or access databases.

Upgrading Your DatabasesYour old 4.1 or 5.0 databases are automatically updated when you first usethem with the new 6.0 or 7.0 server product. Once your databases areupdated, they are incompatible with older server utilities or older tools (exceptvia the Relay Module locally or via INFORMIX-NET over a network).


2Chapter

Summary of Enhancements

Enhanced Statements . . . . . . . . . . . . . . . . . . 2-3CASE . . . . . . . . . . . . . . . . . . . . . . 2-3CONSTRUCT . . . . . . . . . . . . . . . . . . . 2-4GLOBALS . . . . . . . . . . . . . . . . . . . . 2-5LOAD . . . . . . . . . . . . . . . . . . . . . . 2-5PROMPT . . . . . . . . . . . . . . . . . . . . . 2-6UNLOAD. . . . . . . . . . . . . . . . . . . . . 2-6

New and Enhanced Environment Variables . . . . . . . . . . 2-6

Error Messages . . . . . . . . . . . . . . . . . . . . 2-7

Changes to the 4GL Programmer’s Environment . . . . . . . . 2-7

Changes to 4GL Internals. . . . . . . . . . . . . . . . . 2-9

SQL Statements That Cannot Be Prepared . . . . . . . . . . . 2-12

2-2 INFO

his chapter summarizes the 4GL Release 6.0 enhancements. Completeinformation on these enhancements appears in subsequent chapters of thissupplement.

Enhanced StatementsThe 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 thesestatements. For complete information on these enhancements, see Chapter 6,“4GL Statement Syntax.”

CASEBoth 4GL compilers (C4GL and FGLPC) accept CASE statements with WHENclauses. For more information, see “CASE” on page 6-6.

T

Summary of Enhancements 2-3

CONSTRUCT

CONSTRUCTThis statement now supports the following clauses and statements, givingyou 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 firstfilling the fields listed in the CONSTRUCT statement with blanks and beforethe user can enter values into the form fields. When the user presses theAccept key, 4GL executes the statements in the AFTER CONSTRUCT clausebefore constructing the Boolean expression.

4GL executes the group of statements in a BEFORE FIELD clause when a usermoves the cursor into the identified field. Similarly, 4GL executes the groupof statements in the AFTER FIELD clause after the user moves the cursor outof the identified field.

4GL executes the group of statements in an ON KEY clause if the user pressesone of the identified keys while performing the query-by-example.

Use the NEXT FIELD statement to move the cursor to a particular field or tothe NEXT or PREVIOUS form field. NEXT places the cursor in the next field asidentified by the CONSTRUCT statement. PREVIOUS places the cursor in theprevious field as identified by the CONSTRUCT statement.

The CONTINUE CONSTRUCT statement skips all subsequent statementswithin the CONSTRUCT statement and returns the cursor to the screen formso that the user can enter more query-by-example values.

The EXIT CONSTRUCT statement causes 4GL to skip all statements betweenthe EXIT CONSTRUCT statement and the END CONSTRUCT statement and tocreate the character variable containing the Boolean expression.


GLOBALS

During CONSTRUCT, when you enter criteria into a field and are using theAUTONEXT attribute, if you key past the form field delimiter, the cursor doesnot 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 providesufficient 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.

GLOBALSThe overview of GLOBALS in the INFORMIX-4GL Reference defines two formsof the GLOBALS statement: one defines variables, the other refers to the filewhere global variables are defined. This section describes how to eliminatethe possibility of doubly defined variables.

For more information, see “GLOBALS” on page 6-44.

LOADBeginning with Version 6.01, you can do one of the following when thedatabase has a transaction log:

■ Run the LOAD as its own transaction, so that any error causes theentire LOAD statement to be automatically rolled back (implicittransaction).

■ Run the LOAD within an explicit transaction, so that a data errormerely stops the LOAD statement in place with the transaction stillopen.

For more information, see “LOAD Statement Transaction Management” onpage 6-94.


PROMPT

PROMPTIn current releases of 4GL, you need to ensure that the length of the displaylist for the PROMPT statement is smaller than the number of columns on theactive window, in order to avoid a runtime error.

For more information, see “PROMPT” on page 6-113.

UNLOADThe UNLOAD statement now supports host variables in the WHERE clause ofthe embedded SELECT query.

For more information, see “UNLOAD” on page 6-115.

New and Enhanced Environment VariablesThe following environment variables are either new or enhanced in thisversion 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.”


Error Messages

Error MessagesIn Release 6.0 of 4GL, several error messages have been added, updated, anddeleted.

For descriptions of the new and modified error messages and information onaccessing the error message files, see Chapter 8, “Error MessageModifications.”

Changes to the 4GL Programmer’s EnvironmentThis release of 4GL increases uniformity and consistency between theCompiled-4GL Programmer’s Environment (I4GL) and the Rapid Devel-opment System Programmer’s Environment (R4GL).

The I4GL and R4GL programs acknowledge the PROGRAM_DESIGN_DBSenvironment variable that lets the you choose where to store the programinformation. A Program Design database stores build dependencies for 4GLprograms. By default, this information is stored in the syspgm4gl database.When you want to develop a program using I4GL or R4GL, the programsearches for a Program Design database. If the program cannot find thedatabase, it creates one for you. You can choose the name of the database. Ifthe program information is part of your database, it is much easier to exportand import the information using this version of 4GL rather than previousversions.

In the earlier versions of 4GL, the Module/Modify option of I4GL and R4GLprograms found files with long names, but it did not distinguish betweennames such as:

■ a1234567890bcdefghijklmnopq.4gl

■ a1234567890bcdefghijklmnopqrstuvwxyz.4gl

Now the I4GL and the R4GL Program Design database schemas only allow 10characters 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.


Changes to the 4GL Programmer’s Environment

Both the I4GL and R4GL programs have a Query-Language option that runsisql -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 theearlier releases, if ISQL was not available, neither I4GL nor R4GL ranDBACCESS.

There is no limit to the number of 4GL modules, libraries, global files, orobjects you can include in your I4GL and R4GL programs because the size ofthe tables that hold the information dynamically increases. If you add several4GL modules to a program, the size of the table that holds the names of the4GL files increments dynamically by 25%.

For example, if the original size of the table that holds the names of the 4GLfiles is 100 entries, the table grows by 25 entries every time it dynamicallyincreases. If you want to add another 40 modules, you need to do so in twostages. You are allocated 25 entries each time. After you enter the names ofthe first 25 modules, press ESC to return to the menu. Then add the remaining15 modules.

The new R4GL environment recompiles all the non-global files when youupdate any global files, whereas in the earlier releases, the files that wererecompiled depended on the order in which the server returned the data.Thus, if a global file was changed and recompiled, it forced all subsequentfiles to be recompiled, but it did not force prior files to be recompiled. Nowevery non-global object file is recompiled if any of the global source files ismore 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, andotherobj as part of the syspgm4gl database. The new versions of I4GL andR4GL create Program Design databases that contain all the above specifiedtables. The new environments automatically upgrade the older I4GLdatabases so that they contain all seven tables.

If you delete only the executable(.4ge), the newer version of I4GL links theexisting .o files and creates the executable, whereas the older versions of I4GLrecompiled all the source files and linked the newly created object files tocreate an executable.


Changes to 4GL Internals

Changes to 4GL InternalsThe following errors are eliminated in this release of 4GL:

■ The 4GL program cannot allocate any more space for temporarystring 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 stringspace (TSS) is recovered whenever you exit a function or at the completion ofa statement with a USING clause or string concatenation operation, so the TSSdoes not now become continuously filled.

The internal operation of the memory allocation system has been completelyrewritten. Any code that relies on the function acdealloc() will fail becausethat function has been eliminated. Any code that relies on being able to accessalloctab will fail, because that structure has also been eliminated. All suchcode was using undocumented and unsupported knowledge of the internalsof I4GL. If necessary, you can supply a dummy version of acdealloc() thatdoes 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 withoutrecompilation, but you must relink custom runners and debuggers. Unlessthere is compiled 4GL code built into the runner, there is no need to recompilethe component object modules.

Any compiled I4GL program does not gain any benefit from the new TSShandling without relinking. If you simply relink the programs, they will runout of memory when the system declines to give them any more memory. Ifyou completely recompile I4GL programs, they should not run out ofmemory unless you are doing a computation that uses up all the memory.



The following code demonstrates the removal of the limits imposed by error-4518. A program that uses up all the memory would almost certainly haveto use a recursive function such as the Ackerman function, as in the followingcode. This code has a deliberate bug in it because it uses a string as the returnvalue, whereas it should be DECIMAL(32,0) (effectively a giant INTEGER) tobe consistent with the arguments.

MAINDEFINE

i DECIMAL(32,0),j DECIMAL(32,0),a CHAR(60)LET i = 3 -- Be wary about increasing thisLET j = 3LET a = "Result of ACKERMAN(",

i USING "&", ",", j USING "&", ") = ",Ackerman(i, j)

DISPLAY a CLIPPED

END MAIN

FUNCTION Ackerman(m, n)

DEFINEm DECIMAL(32,0),n DECIMAL(32,0),k CHAR(32)

CASEWHEN (m = 0)

LET k = n + 1WHEN (n = 0)

LET k = Ackerman(m - 1, 1)OTHERWISE

LET k = Ackerman(m - 1, Ackerman(m, n - 1))END CASE

RETURN k

END FUNCTION



This code demonstrates the removal of the limits imposed byerror -4517.

MAIN

CALL func1()

END MAIN

FUNCTION func1()

DEFINEstr CHAR(2048),i 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)

DEFINEstr CHAR(2048),i SMALLINT

DISPLAY "String = ", str CLIPPED

LET str = "B"FOR i = 2 to 2048

LET str[i] = "B"END FOR

RETURN str

END FUNCTION


SQL Statements That Cannot Be Prepared

SQL Statements That Cannot Be PreparedYou cannot prepare the following SQL statements because the servers do notunderstand these operations:

■ LOAD

■ UNLOAD

■ CHECK TABLE

■ REPAIR TABLE

■ INFO

■ OUTPUT


3Chapter

Using the 6.0 4GLEnhancements

Managing Screen Interactions . . . . . . . . . . . . . . . 3-3Managing Queries by Example . . . . . . . . . . . . . 3-4Managing Screen Input . . . . . . . . . . . . . . . . 3-6Creating Menus . . . . . . . . . . . . . . . . . . 3-7Moving the Cursor Around a Form . . . . . . . . . . . . 3-8Determining the Initial Values to Display in Fields . . . . . . 3-9Manipulating the Values in Screen Field Buffers . . . . . . . 3-10Determining the Last Keystroke . . . . . . . . . . . . . 3-11Determining When a User Enters a Value in a Field . . . . . . 3-12Defining Fields with the INVISIBLE and BLACK Attributes . . . 3-12

The INVISIBLE Attribute . . . . . . . . . . . . . . 3-13

Querying Tables . . . . . . . . . . . . . . . . . . . . 3-14UNION and UNION ALL . . . . . . . . . . . . . . . 3-15UNION ALL and SELECT DISTINCT (or SELECT UNIQUE) . . . 3-16

Using Variables as Identifiers . . . . . . . . . . . . . . . 3-17

Using the ANSI-Compliant Enhancements . . . . . . . . . . 3-17Specifying Lowercase User Names . . . . . . . . . . . . 3-18Using Cursors to Update Rows . . . . . . . . . . . . . 3-18Determining a Statement That Returns No Rows . . . . . . . 3-19Closing a Closed Cursor. . . . . . . . . . . . . . . . 3-19Avoiding the ANSI Reserved Words . . . . . . . . . . . 3-20

Using the upscol Utility Enhancements . . . . . . . . . . . . 3-21Support of VARCHAR, DATETIME,

and INTERVAL Data Types . . . . . . . . . . . . . 3-21Support of Remote Databases . . . . . . . . . . . . . . 3-21

3-2 INFO

Writing Reports . . . . . . . . . . . . . . . . . . . . 3-22Printing a NULL Character in a Report. . . . . . . . . . . 3-22Guidelines on 4GL Report Writing . . . . . . . . . . . . 3-22Using the RETURN Statement in a Report . . . . . . . . . 3-23Parameterless Reports . . . . . . . . . . . . . . . . 3-23Guidelines for Global Variable Usage . . . . . . . . . . . 3-24Temporary Tables Created by Multipass Reports . . . . . . . 3-24The Eight-Column Limit in the ORDER BY Clause. . . . . . . 3-25Input Statements in Reports . . . . . . . . . . . . . . 3-25

Handling 4GL Runtime Errors . . . . . . . . . . . . . . . 3-25Errors and Inconsistencies in Previous Implementations. . . . . 3-27Differences in Default Error Behavior and ANSI Compliance . . . 3-29Changes to 4GL Error Handling . . . . . . . . . . . . . 3-30

Support for Nested and Recursive ICB Statements . . . . . . . . 3-30Early Exits from Nested and Recursive Operations . . . . . . 3-35

Notes on Nested and Recursive Operations . . . . . . . . 3-39Precedence and Associativity of 4GL Operators. . . . . . . . 3-39

Using Segmented Form Fields with WORDWRAP . . . . . . . . 3-40WORDWRAP in REPORTS . . . . . . . . . . . . . . . 3-41Left-justification of Numeric Form Fields . . . . . . . . . . 3-42

Using New REPORT/RUN/OPTION Functionality . . . . . . . 3-42New REPORT Functionality . . . . . . . . . . . . . . 3-42New RUN Functionality . . . . . . . . . . . . . . . . 3-44New OPTION Functionality . . . . . . . . . . . . . . 3-44

FORM MODE and LINE MODE. . . . . . . . . . . . 3-45RUN...RETURNING Clause . . . . . . . . . . . . . . 3-45

New C Functions: popstring( ) and retstring( ) . . . . . . . . . 3-46


he 6.0 Release of INFORMIX-4GL offers a wide range of enhance-ments. This chapter describes how to use the enhancements. The material inthis section builds on information that appears in the INFORMIX-4GLConcepts 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 InteractionsA significant portion of most 4GL applications involves managing screeninteractions with the users of the program. These applications often includeone or more screen forms that allow users to perform common tasks such asretrieving database information, updating this information, and adding newinformation to the database.

T

Using the 6.0 4GL Enhancements 3-3

Managing Queries by Example

This section describes the 6.0 enhancements that affect the way you write 4GLprograms 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. Themaximum screen size 4GL allows is based on the limitations of your terminal,or 600 lines by 600 columns, whichever is smaller.

Managing Queries by ExampleYou can now include the following clauses and statements with theCONSTRUCT 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 actionsof users as they perform a query by example.

Use the BEFORE CONSTRUCT clause to perform a series of actions before theuser begins entering criteria into the screen fields. You can include any 4GLstatement in this clause. You can then use the AFTER CONSTRUCT clause toperform a series of actions after the user finishes entering criteria into thescreen fields and before 4GL constructs the Boolean expression.


Managing Queries by Example

To specify a series of actions to execute before or after the cursor is placed inone 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 certainfunction 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 theNEXT FIELD statement. You can use the NEXT FIELD statement in any of theCONSTRUCT statement clauses, including the BEFORE CONSTRUCT, AFTERCONSTRUCT, BEFORE FIELD, AFTER FIELD, and ON KEY clause.

You can use the CONTINUE CONSTRUCT statement to exit aBEFORE CONSTRUCT, AFTER CONSTRUCT, BEFORE FIELD, AFTER FIELD, orON KEY clause and return the cursor to the form with the CONSTRUCTstatement still in effect. For example, the following CONTINUE CONSTRUCTstatement appears in an AFTER CONSTRUCT clause. If the user specifies N orn to the prompt, the cursor returns to the form:

CONSTRUCT BY NAME query_1 ON customer.*...AFTER CONSTRUCT

IF NOT field_touched(customer.*) THENPROMPT "Do you really want to see ",

"all customer rows? (y/n) "FOR CHAR answer

IF answer MATCHES "[Nn]" THENMESSAGE "Enter search criteria; ",

"press ESC to begin search."CONTINUE CONSTRUCT

END IFEND IF

END CONSTRUCT

Use the EXIT CONSTRUCT statement to terminate the CONSTRUCT statement.4GL skips all the statements between the EXIT CONSTRUCT statement and theEND CONSTRUCT statement.

For more information about the CONSTRUCT statement, see “CONSTRUCT”on page 6-9.


Managing Screen Input

Managing Screen InputYou can now specify BEFORE INPUT and AFTER INPUT clauses and NEXTFIELD and CONTINUE INPUT statements within INPUT and INPUT ARRAYstatements. These clauses and statements give you more flexibility whendeveloping programs that use forms for entering information.

Use the BEFORE INPUT clause to perform processing before the user entersvalues into fields in the form. You can include any 4GL statement in thisclause. You can then use the AFTER INPUT clause to process the enteredvalues when the user finishes with the form.

While the user is entering information into the form, you can control theorder in which the cursor moves to fields by specifying the NEXT FIELDstatement. You can include the NEXT FIELD statement in any of the INPUTstatement clauses. For example, the following INPUT statement specifies anON KEY clause. If the user presses CTRL-B while in either of the specifiedfields, 4GL calls the stock_help( ) function and then places the cursor in thequantity field:

INPUT ARRAY p_items FROM s_items.*...ON KEY (CONTROL-B)

IF infield(stock_num) OR infield(manu_code) THENCALL 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 returnthe cursor to the form.


Creating Menus

Creating MenusYou can now identify menu names and menu-option names by usingcharacter variables or character strings. Also, you no longer need to confineyour 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 canwrite a MENU statement that dynamically shows and hides menu options.Your program can include a single MENU statement that produces custommenus for different users. This means that you need not prepare andmaintain a series of parallel MENU statements; you can use conditional logicto specify which options (and which forms) appear for each user.

The following example demonstrates the use of the SHOW OPTION and HIDEOPTION statements in a MENU statement. The Long_menu option shows alloptions; the Short_menu option shows only the Query, Details,Long_menu, and Exit options. The example also demonstrates using acharacter 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 ALLSHOW OPTION "Query", "Details", "Long_menu", "Exit"

COMMAND "Exit" "Exit the Order Management Form"EXIT MENU

END MENU


Moving the Cursor Around a Form

Moving the Cursor Around a FormYou 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 defaultorder. The default order for a CONSTRUCT or INPUT statement is determinedby the order of the fields listed in the FROM clause or in the order implied bythe column list in the ON clause. The default order for an INPUT ARRAYstatement 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 FIELDORDER UNCONSTRAINED option of the OPTIONS statement. This optioncauses the up and down arrow keys to work as follows:

■ The up arrow key moves the cursor to the nearest field above thecurrent position of the cursor.

■ The down arrow key moves the cursor to the nearest field below thecurrent position of the cursor.


Determining the Initial Values to Display in Fields

Determining the Initial Values to Display in FieldsWhen using the CONSTRUCT, INPUT, and INPUT ARRAY statements, you cancontrol the values displayed in fields when 4GL initially displays the form. Bydefault, the CONSTRUCT statement displays blanks and the INPUT andINPUT ARRAY statements display the default values of the fields. You canoverride this behavior by including:

1. a WITHOUT DEFAULTS clause, if you are using the INPUT or INPUTARRAY 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 thep_customer.city variable and then displays the value on the screen form:

INPUT BY NAME p_customer.fname THRU p_customer.phoneWITHOUT DEFAULTSBEFORE INPUT

LET p_customer.city = "San Francisco"DISPLAY BY NAME p_customer.city

END INPUT


Manipulating the Values in Screen Field Buffers

Manipulating the Values in Screen Field BuffersTo validate, save, or alter the values of the screen field buffers, use theget_fldbuf( ) function. This function returns the character value of the fieldbuffer value. For example, in the following program segment, theget_fldbuf( ) function obtains the value that the user enters in the lname fieldwhen the user presses CTRL-P. It then creates a query based on the value thatthe user entered in the lname field and displays an array of names beginningwith 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,1PREPARE mysubquery FROM myqueryDECLARE q1 CURSOR FOR mysubqueryLET a = 0FOREACH q1 INTO lname

LET a= a + 1...

END FOREACHDISPLAY a TO ncountIF (a = 0) THEN

PROMPT "Nothing beginning with these letters"FOR CHAR partial_name

ELSEIF (a > 10) THEN

LET a = 10END IFCALL set_count(a)DISPLAY ARRAY tw to srec.*

END IF...

END INPUT


Determining the Last Keystroke

Determining the Last KeystrokeYou can tell 4GL to perform tasks based on the last keystroke that the userentered on a form. 4GL compares the last keystroke that a user entered withone of the following values when you use the fgl_lastkey( ) and fgl_keyval( )functions.

For example, the following CONSTRUCT statement includes thefgl_lastkey( ) and fgl_keyval( ) functions in an AFTER FIELD clause. If theuser presses the Accept key after entering a value in the fname field and hasnot entered a value in the lname field, 4GL displays a message telling the userto 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) THENLET key = fgl_lastkey()IF key = fgl_keyval("accept") THEN

IF NOT field_touched(customer.lname) THENMESSAGE "You must enter a last name."NEXT FIELD lname

END IFEND IF

END IFEND CONSTRUCT

ACCEPT INTERRUPT

AUTONEXT LEFT

DELETE NEXTPAGE

DOWN PREVPAGE

ESC RETURN

ESCAPE RIGHT

HELP TAB

INSERT UP

F1 through F64 CTRL-A through CTRL-Z

a printable character


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 FieldTo determine if a user has entered a value in one or more fields, you can usethe field_touched( ) function. This function determines if the user enters oneof the following values in the specified fields:

■ Any printable character✮ CTRL-X

✮ CTRL-D

The field_touched( ) function can appear anywhere within aCONSTRUCT, INPUT, or INPUT ARRAY statement except in the BEFORECONSTRUCT or BEFORE INPUT clause.

The following example checks if the user has entered a value into any formfield:

CONSTRUCT BY NAME query1 ON customer.*...

AFTER CONSTRUCTIF NOT field_touched(customer.*) THEN

PROMPT "Do you really want to see ","all customer rows? (y/n)"FOR CHAR answer

IF answer MATCHES "[Nn]" THENCONTINUE CONSTRUCT

END IFEND IF

END CONSTRUCT

Defining Fields with the INVISIBLE and BLACK AttributesINVISIBLE and BLACK are not new attributes; however, the way in which 4GLdisplays these attributes has changed. If you define an input field asINVISIBLE, 4GL does not display the values a user enters. If you define a fieldas BLACK, 4GL displays the field in BLACK on a color terminal and in DIM ona monochrome terminal.


Defining Fields with the INVISIBLE and BLACK Attributes

As with all attributes, you set the INVISIBLE and BLACK attributes either inthe ATTRIBUTES section of a form specification file or in the ATTRIBUTEclause 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 thecharacters the user types in the field. However, the cursor moves through thefield as the user types.

You can specify the INVISIBLE attribute in the ATTRIBUTES section of a formspecification 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 anATTRIBUTE clause. If you specify the INVISIBLE attribute for the followingstatements, 4GL does not display the text the user types:

■ CONSTRUCT

■ INPUT

■ INPUT ARRAY

■ OPTIONS (the INPUT or DISPLAY ATTRIBUTE clauses)■ PROMPT


Querying Tables

4GL ignores the INVISIBLE attribute for the following statements:

■ DISPLAY

■ DISPLAY ARRAY

■ DISPLAY FORM

■ MESSAGE

■ OPEN WINDOW

By default, the ERROR statement displays error messages in REVERSE. If youspecify only the INVISIBLE attribute for the ERROR statement, 4GL displaysthe error in NORMAL. If you specify the INVISIBLE attribute and anotherattribute, 4GL ignores the INVISIBLE attribute.

The BLACK Attribute

When you specify the BLACK attribute, 4GL displays the output as BLACK ona color terminal and as DIM on a monochrome terminal. Previously, it wasdocumented that BLACK was displayed as INVISIBLE on a monochrometerminal.

Querying TablesYou can combine two or more SELECT statements by placing the UNIONoperator between the statements. Release 6.0 of 4GL allows you to use thefollowing combinations of operators and keywords when combining SELECTstatements:

■ UNION and UNION ALL

■ UNION ALL and SELECT DISTINCT or SELECT UNIQUE


UNION and UNION ALL

UNION and UNION ALLThe UNION operator, placed between two or more SELECT statements,combines the results of the statements into a single result and removes anyduplicate rows. UNION ALL also combines the results of two or more SELECTstatements into one but does not eliminate duplicate rows. In release 6.0,UNION and UNION ALL can appear in the same query without returning anerror.

Because UNION and UNION ALL are both left-associative, you can change theeffect of your SELECT statement by the placement of these keywords and theuse of parentheses.

The following SELECT statement returns duplicate rows. Here, the UNIONoperator eliminates duplicate rows returned from the west_ords andcent_ords tables, but UNION ALL permits duplicate rows to be returned fromthe closed_ords table and from the entire statement:

SELECT customer_num FROM west_ordsUNIONSELECT customer_num FROM cent_ordsUNION ALLSELECT customer_num FROM closed_ords

The next example does not return duplicate rows. Here, UNION ALL permitsduplicate rows to be returned from the cent_ords and the closed_ords tables,but the UNION operator eliminates any duplicates from the UNION ALLoperation as well as any from the west_ords table:

SELECT customer_num FROM west_ordsUNION(SELECT customer_num FROM cent_ordsUNION ALLSELECT customer_num FROM closed_ords)

If you enclose a SELECT statement in parentheses, be careful with thestatement that precedes the SELECT statement. Do not precede the SELECTstatement with a statement that can optionally conclude with a clauseenclosed in parentheses. If you omit the clause enclosed in parentheses, 4GLtries to use the SELECT statement as a part of the previous statement.


UNION ALL and SELECT DISTINCT (or SELECT UNIQUE)

For example, the following example results in an error message because 4GLinterprets the SELECT statement as part of the definition of the name variable:

DEFINE name CHAR(SELECT customer_num FROM west_ords

UNIONSELECT customer_num FROM cent_ords)UNION ALLSELECT customer_num FROM closed_ordsINTO TEMP all_cnums

You can avoid this ambiguity by placing a statement between the DEFINEstatement and the SELECT statement.

UNION ALL and SELECT DISTINCT (or SELECT UNIQUE)The keywords UNION ALL and SELECT DISTINCT (or SELECT UNIQUE) canappear in the same SELECT statement. This feature allows greater flexibilityin determining which rows are returned as duplicates.

For example, the following SELECT DISTINCT statement eliminates duplicaterows returned from the west_ords table, while the SELECT statement canretrieve duplicate rows from the closed_ords table. The keywords UNIONALL permit the return of any duplicate rows from closed_ords as well as anyduplicates between closed_ords and west_ords.

SELECT DISTINCT customer_num FROM west_ordsUNION ALLSELECT customer_num FROM closed_ords


Using Variables as Identifiers

Using Variables as IdentifiersSome 4GL statements now allow you to use a character variable in additionto a quoted string constant when naming a file or listing the elements of amenu. In particular, you can use character variables to identify the following.

These variables must be of the type CHARACTER or VARCHAR.

Variable assignments must occur before they are used in the statement,except in the case of the MENU statement. In the MENU statement, you canassign a value to the variable within the BEFORE MENU clause or in one ormore of the COMMAND clauses. For complete information on specifyingvariables in the MENU statement, see the section titled “Using Variables in aMENU Statement” on page 6-108.

Using the ANSI-Compliant EnhancementsRelease 6.0 of 4GL offers several enhancements that affect users withANSI-compliant databases. This section discusses the ANSI-compliantenhancements and how they relate to the following:

■ Specifying lowercase user names

■ Determining a statement that returns no rows

■ Using cursors to update rows

■ Closing a closed cursor

■ Avoiding the ANSI reserved words

Statement Identifiable with Variables

MENU menu-name, option-name,and option-description

OPEN FORM form-file

OPEN WINDOW form-file

OPTIONS help-file


Specifying Lowercase User Names

If you do not work with ANSI-compliant databases, you can disregard thissection.

Specifying Lowercase User NamesThe ANSI standard requires that all identifiers, including user names, be inuppercase letters. For this reason, when you specify a user name thatincludes any lowercase letters, 4GL automatically converts the name intouppercase letters before passing the name to the engine.

To specify a user name that is all lowercase or is a combination of uppercaseand lowercase letters, you must enclose the name in quotes. 4GL passes anyuser name enclosed in quotes on to the engine with the case of the lettersintact. When a user specifies this name, quotes must be placed around thename.

The only time when 4GL does not convert an unquoted, lowercase user nameto uppercase is when the user name is informix or public.

The following example specifies the name “james” as the owner of the tablecustnotes:

CREATE TABLE "james".custnotes(customer_num INTEGER, notes CHAR(240))

You can access the table as shown in the following example:

SELECT * FROM "james".custnotes

Using Cursors to Update RowsIn an ANSI-compliant database, you can update or delete the current row byusing a cursor that has not been declared as FOR UPDATE. This enhancementallows ANSI-compliant applications to update the current row. (The ANSIstandard does not support the FOR UPDATE clause on the DECLARE CURSORstatement.)


Determining a Statement That Returns No Rows

You can update or delete a non-scrolling cursor declared for a SELECTstatement that:

■ selects data from only one table.

■ does not include any aggregate functions.

■ does not include any of the following keywords or clauses:

❑ DISTINCT or UNIQUE

❑ UNION or UNION ALL

❑ GROUP BY

❑ ORDER BY

Note that if you do update a row with a cursor that has not been declared FORUPDATE, you are more likely to run into locking conflicts. The databaseengine does not place an update lock on a row read by such a cursor, whereasa cursor declared FOR UPDATE locks each row that is read in.

Determining a Statement That Returns No RowsIn an ANSI-compliant database, 4GL returns the status code 100 when any ofthe following statements result in no rows being found:

■ DELETE

■ INSERT INTO ... SELECT

■ SELECT ... INTO TEMP

■ UPDATE

If the database is not ANSI-compliant, and any of these statements result inno rows being found, the engine returns the status code 0.

Closing a Closed CursorIn an ANSI-compliant database, 4GL does not allow you to close a cursor thatis currently closed. If you try to close a closed cursor, 4GL displays an errormessage.


Avoiding the ANSI Reserved Words

The following statements can close a cursor:

■ CLOSE

■ CLOSE DATABASE

■ COMMIT WORK

■ DATABASE

■ ROLLBACK WORK

Avoiding the ANSI Reserved WordsIf you have an ANSI-compliant table, several words are reserved. 4GLgenerates a warning if you include an ANSI reserved word in a statement andone of the following is true:

■ The DBANSIWARN environment variable is set.

■ You specify the -ansi flag.

The ANSI reserved words are as shown in the following table.

all cursor goto of smallintand dec grant on someany decimal group open sqlas declare having option sqlcodeasc delete in or sqlerroravg desc indicator order sumbegin distinct insert pascal tablebetween double int pli toby end integer precision unionchar escape into privileges uniquecharacter exec is procedure updatecheck exists language public userclose fetch like real valuescobol float max rollback viewcommit for min schema whenevercontinue fortran module section wherecount found not select withcreate from null set workcurrent go numeric


Using the upscol Utility Enhancements

Using the upscol Utility EnhancementsThe upscol utility has the following enhancements:

■ Support of the VARCHAR, DATETIME, and INTERVAL data types

■ Support of remote databases

This section describes these enhancements.

Support of VARCHAR, DATETIME, and INTERVAL Data TypesThe upscol utility now supports the VARCHAR, DATETIME, and INTERVALdata types. The utility now recognizes all Informix data types except TEXT orBYTE.

Support of Remote DatabasesWhen using the upscol utility, you can now specify remote database names.A remote database resides on a different OnLine system than the currentdatabase. To specify a remote database name, use the following format:

database@servername

where database is the name of the database and servername is the name of thedatabase’s server. For example, the following screen shows how to specify aremote database named payables on a server named phoenix:

CHOOSE DATABASE >> payables@phoenixChoose a database with the Arrow keys or enter a name, and press RETURN.-------------------------------------------------Press CTRL-W for Help


Writing Reports

Writing ReportsRelease 6.0 of 4GL contains the following changes to report processing:

■ The ability to print 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

Printing a NULL Character in a ReportTo print a NULL character in a report, call the ASCII function with 0 in a PRINTstatement. For example, the following statement prints the NULL character:

PRINT ASCII 0

ASCII 0 only displays the NULL character when used with a PRINT statement.If you call the ASCII 0 in other cases, 4GL displays a blank space.

Guidelines on 4GL Report WritingThe compilers do not allow the following statements within report functions.However, these statements can be executed by functions that are called fromwithin the body of a report:

■ PROMPT

■ INPUT

■ INPUT ARRAY

■ DISPLAY ARRAY

■ CONSTRUCT


Using the RETURN Statement in a Report

Using the RETURN Statement in a ReportNever use the RETURN statement in a REPORT function because it is designedfor use in regular 4GL functions only. However, the compilers allow you touse the RETURN statement in a REPORT. To stop processing a given reportwithout aborting the program, set a global flag that is tested in your reportdriver function (where the OUTPUT TO REPORT statements are located). If theflag value indicates a problem, finish the report and ignore the output.

If your report uses ORDER BY (without the EXTERNAL keyword), if you use aWHERE clause with any aggregate (as described in the INFORMIX-4GLReference), or if you use non-GROUP aggregates in any control block otherthan the ON LAST ROW control block, the report is processed as a multipassreport. This means that the report function's control blocks do not executeuntil all data has been gathered and the FINISH REPORT statement has beenreached in the report driver function. At this point the report functionexecutes as a unit, and you cannot programmatically abort it from withinbecause you cannot use the RETURN statement.

Parameterless ReportsYou can use parameterless reports for very specialized reports, but theirbehavior is not intuitively obvious. In particular, aggregates only workreliably when you apply them to parameters to reports, and not when youapply them to global or local variables. Additionally, you must order theparameters.


Guidelines for Global Variable Usage

Guidelines for Global Variable UsageYou can use module global or program global variables in reports. This canprovide performance benefits. However, the use of globals in multipassreports might yield unexpected results.

If you know that your report is not a multipass report and you refer tovariables that are not used as control information in the report (for example,they are not referenced in BEFORE/AFTER GROUP OF clauses or in aggre-gates; they are merely printed), any such variables can be global variables.Passing long character strings as global variables instead of report param-eters can result in a noticeable improvement in performance, if these otherconditions are met. You can use any global variables that will not change invalue while generating the report, even in multipass reports if these otherconditions are met.

In a multipass report, most references to a global variable are executed,yielding unexpected results if the global variable value changes betweenOUTPUT TO REPORT statements.

Temporary Tables Created by Multipass ReportsA multipass report creates a temporary table to hold the data that theOUTPUT TO REPORT statements send to the report as rows. The report createsthe temporary tables by prefixing the report name with t_.

In much earlier versions of 4GL, a report that had a name with 17 or morecharacters tried to create a temporary table with 19 or more charactersresulting in a runtime error. This is no longer a problem because now thenames of the temporary tables are truncated at 18 characters. The first 16characters in reports that run concurrently should still be distinct becauseotherwise the second one will encounter table exists errors.

Do not design a database with tables whose names start t_ because thisrestricts the names that you can use for report functions. The temporarytables are inherently private to the user running the report, so there is noconflict with multiple users running the same report, nor with the same userrunning the same report in different windows.


The Eight-Column Limit in the ORDER BY Clause

The Eight-Column Limit in the ORDER BY ClauseIn previous versions of 4GL, there was an eight-column limit in the ORDER BYclause. This limitation no longer applies.

Input Statements in ReportsCertain types of statements, which used to be syntactically allowed but werenot intended to be allowed in 4GL reports, now get syntax errors. Theseinclude:

■ INPUT

■ INPUT ARRAY

■ PROMPT

■ MENU

■ CONSTRUCT

■ DISPLAY ARRAY

■ RETURN

Handling 4GL Runtime ErrorsSome inconsistencies exist in both 4GL error handling and betweenC-compiled 4GL and the 4GL Rapid Development System (RDS). Startingwith this release, both 4GL variants have a more intuitive error handlingregimen than previously. These changes have some serious compatibilityeffects, especially for RDS users.

To better understand the impact of these changes, review the concepts oferror handling and the WHENEVER statement in the INFORMIX-4GLReference Version 6.0. Then read this section to understand the impact of thesechanges on your applications’ error handling techniques.


Handling 4GL Runtime Errors

In this section the term Error Scope refers to whether the scope of errorhandling includes expression errors. Normal Error Scope includes SQL errors,validation errors discovered by the VALIDATE statement, and screen inter-action statement errors, but it ignores expression errors. Expression errorsneither initiate any action requested by a WHENEVER statement, nor do theyset the STATUS variable.

This Normal Error Scope behavior was the 4GL behavior through 4GL version1.10.03. It was restored in Version 4.10 after customers encountered compati-bility issues with the 4.0 release when their applications could not handle itsmore restrictive AnyError Error Scope.

In contrast, AnyError Error Scope means that expression errors also activateerror logic, and STATUS is set to an appropriate negative value after thestatement that produced the expression error. This was the only Error Scopeavailable with Version 4.0 of 4GL. Now, however, you must request itmanually by using the WHENEVER ANY ERROR directive or by using the-anyerr flag when you compile or when you use the RDS runner or debuggercommand line.

For maximum ease in preventing, locating, and correcting expression errors,we recommend that you write all new 4GL code to work under AnyErrorError Scope. With compiled 4GL, you can achieve this automatically bysetting the C4GLFLAGS environment variable to include -anyerr. With RDS,you can achieve this by setting the FGLPCFLAGS environment variable toinclude -anyerr. Note that C4GLFLAGS was first supported in Version 6.00,but FGLPCFLAGS was first supported by Version 6.01.


Errors and Inconsistencies in Previous Implementations

Errors and Inconsistencies in Previous ImplementationsThe C-compiled version of 4GL (C4GL) preceded the first release of the inter-preted Rapid Development System (RDS) version by several years. Therefore,there have always been some minor behavioral differences between C4GLand RDS variants of a given release. Most such behavior differences areconsidered bugs and the two variants are kept as similar in performance aspossible.

One key difference is conversion errors in expressions. RDS performs mostdata type conversions internally without relying upon generic 4GL librarycalls. Prior to this release, RDS used to perform these internal expressionconversions as if AnyError Error Scope was always in effect. Therefore, RDSappeared to support only AnyError Error Scope. Only those expressions orconversions that required 4GL library calls would reveal this inconsistency.For example:

DEFINE xd DATE

LET xd = DATE("14/14/90") DISPLAY "status = ", status

LET xd = "14/14/90" DISPLAY "status = ", status

In this example, the LET statements are logically equivalent. However, whenrun in RDS under Normal Error Scope, the first LET would not set STATUS,since a 4GL library call is used; the second would set STATUS and wouldterminate the program unless you used WHENEVER ERROR to specifynonfatal error handling.

The other major category of error mishandling with previous versions wasthat expression errors would produce error messages on the UNIX standarderror file (normally, the user's screen) that the application could not trap. Thisis appropriate behavior for fatal errors, but for errors that the application canhandle, (for example, SQL errors, validation errors discovered by theVALIDATE statement, and screen interaction statement errors), it is, at theleast, disruptive to the user.


Errors and Inconsistencies in Previous Implementations

For example, to prompt the user to enter a date value using the PROMPTstatement, keep (for reference) the exact character string the user entered andcheck that the date entered was valid. The following code is an example ofthis.

DEFINE xd DATE, xc CHAR(12)

WHENEVER ERROR CONTINUE

PROMPT "Enter date: " FOR xc

LET xd = xc -- If invalid date, will give errorif (STATUS != 0) THEN -- if AnyError Error Scope in effect... -- (error handling code)

Under previous releases an invalid date value would have resulted in thefollowing untrappable error message on the standard error file (and in theerror log file, if one exists) in C4GL programs with Normal Error Scope:

Enter date: 131313

Program stopped at "<name>", line number X.

FORMS statement error number -1205. Invalid month in date

However, STATUS would be unchanged, and program execution wouldcontinue.

There was no easy way for the developer to prevent that message from beingdisplayed on the screen (because STATUS was not set, the programmer couldnot even detect within the program that the error event had occurred), evenif it was an expected event that the 4GL programmer otherwise could havehandled.


Differences in Default Error Behavior and ANSI Compliance

Differences in Default Error Behavior and ANSI ComplianceThe default responses to error conditions differ between the ANSI-compliantmethod and the non-ANSI-compliant method as follows:

1. If ANSI compliance is requested and no WHENEVER statement is ineffect, the default action after an error is to CONTINUE.

ANSI compliance is in effect if one of the following conditions exists:

■ There is a stated default database and it is ANSI-compliant.

■ The -ansi compilation flag is specified.

■ The DBANSIWARN environment variable is set.

In previous releases of RDS, for the last two of these three conditions,the default error action was improperly left at STOP instead ofCONTINUE. This no longer happens.

2. If ANSI compliance is not in effect and no WHENEVER statement is ineffect:

■ If the -anyerr flag is used, the default action is STOP.

■ If, instead, the -anyerr flag is not used, the default action afterexpression/ type conversion errors is CONTINUE; after othercategories of errors, it is STOP.

The error behavior depends on the database that the non-proceduralDATABASE statement references when you compile the program. Ifyou compile against a non-ANSI-compliant database and run againstan ANSI-compliant database, the error behavior is as though thedatabase is not an ANSI-compliant database. The converse alsoapplies: if you compile against an ANSI-compliant database but runagainst a non-ANSI-compliant database, the error behavior is asthough the database is an ANSI-compliant database.

If you compile part of the application against an ANSI-compliantdatabase and part of it against a non-ANSI-compliant database, thenthose parts of the application compiled against the ANSI-compliantdatabase have the default error action of CONTINUE and those partscompiled against the non-ANSI-compliant database have the defaulterror action of STOP.


Changes to 4GL Error Handling

Changes to 4GL Error HandlingBeginning with Release 6.01, the following changes in error handling are ineffect:

■ STATUS is set for expression errors only if AnyError Error Scope isin effect. AnyError behavior is no longer mostly assumed for RDS.

This is a significant backward-compatibility concern for RDS userswho do not currently explicitly use AnyError Error Scope. Youshould use the -anyerr flag when compiling your p-code modules(and recompile any other existing pcode modules in the sameprogram, for consistency within each program) to prevent surprisefailures of expression errors to set STATUS.

■ Nonfatal, untrappable messages are no longer written to the UNIXstandard error file. They are written to the 4GL error log file only.

If a fatal error condition occurs, appropriate messages are stillwritten to both the standard error file (usually, the user's screen) andthe error log file (if one has been established for the application usingthe startlog( ) library call). However, from now on, nonfatal errormessages are recorded only in the error log file.

This is a noticeable change primarily for C4GL programs that usedNormal Error Scope because most RDS expression/conversion errorshad traditionally used AnyError behavior regardless of requestedError Scope.

Application developers should use 4GL error logs in order torecognize and isolate nonfatal errors.

Support for Nested and Recursive ICB Statements4GL statements such as CONSTRUCT, DISPLAY ARRAY, INPUT, INPUT ARRAY,and PROMPT are collectively referred to as ICB statements and use a commonunderlying data structure called the Input Control Block (ICB). 4GL nowsupports nested and recursive ICB statements in which the parent and thechild ICB statements use the same form for accepting and displaying thedata. In the case of recursive ICB statements, the parent and the child state-ments can be the same.


Support for Nested and Recursive ICB Statements

4GL now supports both direct and indirect nesting of the ICB statementswhere the level of nesting is limited only by the availability of the resources.Direct nesting involves embedding the child ICB statement in one of theclauses such as ON KEY, BEFORE FIELD, AFTER FIELD, and so forth, of theparent ICB statement. The following code sample illustrates direct nesting ofINPUT statements:

MAIN DEFINE r1, r2 RECORD f1, f2, f3 CHAR(30)END RECORDDATABASE nestedinputDBDEFER INTERRUPTOPEN FORM nest_form FROM "nested_input"DISPLAY FORM nest_form LET INT_FLAG = FALSEIF NOT INT_FLAG THEN INPUT BY NAME r1.* WITHOUT DEFAULTS --Parent INPUT stmtBEFORE INPUTMESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1BEFORE FIELD f1MESSAGE "Input Statement 1 -- BF1" SLEEP 1AFTER FIELD f2MESSAGE "Input Statement 1 -- AF1" SLEEP 1--Child INPUT Statement INPUT BY NAME r2.* WITHOUT DEFAULTS --Child INPUT stmtBEFORE INPUTMESSAGE "BEFORE INPUT STATEMENT 2" SLEEP 1AFTER INPUTMESSAGE "AFTER INPUT STATEMENT 2" SLEEP 1ON KEY (CONTROL-W)MESSAGE "IP2: HELP IS NOT AVAILABLE" SLEEP 1END INPUT --End of Child INPUT stmtLET r2.f1 = "Child INPUT Statement -- ", r2.f1 CLIPPEDINSERT INTO table_2 VALUES(r2.*)AFTER INPUTMESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1ON KEY (CONTROL-W)MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1END INPUT --End of Parent INPUT stmtEND IFLET r.f1 = "Parent INPUT Statement -- ", r1.f1 CLIPPEDINSERT INTO table_1 VALUES(r1.*) MESSAGE "Input Statement -- complete" SLEEP 1

END MAIN



In this example of nested INPUT statements, the parent and the child state-ments use the same form for entering data. After you enter data in fields f1and f2 for the parent INPUT statement, control transfers to the child INPUTstatement. Once the child INPUT statement is executed, data entered for thechild is inserted in table_2. Then control returns to the parent and fields f1and f2 are restored to their original values.

Indirect nesting invokes a function, which contains the child ICB statement,from the parent ICB statement. Once again, the parent and the child ICB state-ments use the same form for data entry. The following code illustratesindirect nesting of INPUT statements:



MAINDEFINE r1 RECORDf1, f2, f3 CHAR(30)END RECORDDATABASE nestedinputDBDEFER INTERRUPTOPEN FORM nest_form FROM "nested_input"DISPLAY FORM nest_formLET INT_FLAG = FALSE

IF NOT INT_FLAG THENINPUT BY NAME r1.* WITHOUT DEFAULTS--Parent INPUT stmtBEFORE INPUTMESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1BEFORE FIELD f1MESSAGE "Input Statement 1 -- BF1" SLEEP 1AFTER FIELD f2MESSAGE "Input Statement 1 -- AF1" SLEEP 1 --Indirect NestingCALL child_inputstmt()AFTER INPUTMESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1 ON KEY (CONTROL-W)MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1END INPUT --End of Parent INPUT stmt

END IFLET r.f1 = "Parent INPUT Statement -- ", r1.f1 CLIPPEDINSERT INTO table_1 VALUES(r1.*)MESSAGE "Input Statement -- complete" SLEEP 1

END MAINFUNCTION child_inputstmt()

DEFINE r2 RECORDf1, f2, f3 CHAR(30)END RECORDLET INT_FLAG = FALSE

IF NOT INT_FLAG THENINPUT BY NAME r2.* WITHOUT DEFAULTS --Child INPUT stmtBEFORE INPUTMESSAGE "BEFORE INPUT STATEMENT 2" SLEEP 1AFTER INPUTMESSAGE "AFTER INPUT STATEMENT 2" SLEEP 1 ON KEY (CONTROL-W)MESSAGE "IP2: HELP IS NOT AVAILABLE" SLEEP 1END INPUT --End of Child INPUT stmt

END IFLET r2.f1 = "Child INPUT Statement -- ", r2.f1 CLIPPEDINSERT INTO table_2 VALUES(r2.*)

END FUNCTION

Performing heterogeneous nesting is valid where the parent and the childstatements are entirely different. For example, where CONSTRUCT is theparent statement, INPUT can be the child statement.



The recursive ICB statements feature provides extra flexibility to 4GLprogrammers. The following sample code illustrates the use of the recursiveINPUT statement:

MAINDEFINE r RECORDf1, f2, f3 CHAR(30)END RECORDDEFINE z INTEGERDATABASE recinputDBDEFER INTERRUPTOPEN FORM recurs_form FROM "recursive_input"DISPLAY FORM recurs_formLET z = 0CALL recursive_input(z, r)

END MAINFUNCTION recursive_input(z1, r1)

DEFINE r1 RECORDf1, f2, f3 CHAR(30)END RECORDDEFINE z1 INTEGERLET INT_FLAG = FALSELET z1 = z1 + 1IF z1 > 3 THENRETURNEND IFMESSAGE "Recursive Cycle: ", z1 SLEEP 1

IF NOT INT_FLAG THENINPUT BY NAME r1.* WITHOUT DEFAULTSBEFORE INPUTMESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1BEFORE FIELD f1MESSAGE "Input Statement 1 -- BF1" SLEEP 1AFTER FIELD f2MESSAGE "Input Statement 1 -- AF1" SLEEP 1CALL recursive_input(z1, r1) --Recursive callAFTER INPUTMESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1ON KEY (CONTROL-W)MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1END INPUT

END IFLET r.f1 = "Recursive Cycle -- ", z1, r1.f1 CLIPPEDINSERT INTO table_1 VALUES(r1.*)MESSAGE "Input Statement -- complete" SLEEP 1

END FUNCTION


Early Exits from Nested and Recursive Operations

For every recursive invocation of the function recursive_input( ), the sameform is used for data entry. A recursive call is made after you enter data infields f1 and f2 for each invocation. Before making a recursive call, context isstored in dynamically allocated variables and pushed onto the stack. Whenthe terminating condition for recursion is satisfied, context pops out of thestack and the form fields f1 and f2 revert to their original values.

It is valid to combine all the different types of nesting such as direct, indirect,heterogeneous, and homogeneous with recursive ICB statements. To avoidanomalous behavior, it is advisable to recompile and relink applications thatuse ICB-related statements with current software.

Early Exits from Nested and Recursive OperationsThe new nested input features allow some operations that can cause 4GL toclean up incorrectly during INPUT, INPUT ARRAY, DISPLAY ARRAY,CONSTRUCT, MENU, and FOREACH loops.

For any nested statements, an early exit from inside one of the inner state-ments to one of the outer statements, or a RETURN, means that 4GL does notclean up any statement except the innermost statement.

The following code, though of no practical use, illustrates how you can usenested INPUT statements. There are nine levels of nested statements in thecode. It also illustrates some problems caused by early exits from nestedstatements. For example, when you do an EXIT FOREACH from inside anINPUT statement nested inside two MENU statements, a FOR loop and aWHILE loop (as shown by the first EXIT FOREACH statement), then the inter-vening menus (“ABCDEF” and “XYZ”) are not cleaned up correctly, thoughthe INPUT statement itself is handled correctly and the FOREACH loop cursorcloses correctly.

GOTO statements, including WHENEVER ERROR GOTO or WHENEVERWARNING GOTO are not dealt with properly. If this is a concern, do not useGOTO.



MAINCALL f()

END MAINFUNCTION f()

DEFINE s CHAR(300)DEFINE y INTEGERDEFINE i INTEGERDEFINE t INTEGERDEFINE a ARRAY[10] OF INTEGERDECLARE c CURSOR FORSELECT Tabid FROM SystablesOPEN WINDOW w AT 1, 1 WITH FORM "xxx"LET y = 0FOREACH c INTO t

FOR i = 1 TO 10WHILE y < 1000MENU "ABCDEF"BEFORE MENUHIDE OPTION "B"COMMAND "A" "Absolutely"SHOW OPTION "B"IF a[1] THEN EXIT MENU END IFIF a[1] THEN CONTINUE MENU END IFNEXT OPTION "E"COMMAND "B" "Beautiful"MESSAGE "Thank you"COMMAND "C" "Colourful"MESSAGE "Thank you"COMMAND "D" "Delicious"MESSAGE "Thank you"COMMAND "E" "Exit"EXIT MENUCOMMAND "F"MENU "XYZ"COMMAND "X"EXIT MENUCOMMAND "Y"INPUT BY NAME y WITHOUT DEFAULTSAFTER FIELD yIF a[1] THEN EXIT FOR END IFIF a[1] THEN CONTINUE FOR END IFIF a[1] THEN EXIT FOREACH END IFIF a[1] THEN CONTINUE FOREACH END IFIF a[1] THEN EXIT WHILE END IFIF a[1] THEN CONTINUE WHILE END IFIF a[1] THEN RETURN END IFIF a[1] THEN EXIT MENU END IFIF a[1] THEN CONTINUE MENU END IFIF a[1] THEN EXIT INPUT END IF



IF a[1] THEN CONTINUE INPUT END IFIF a[1] THEN GOTO End_Label END IFIF a[1] THEN GOTO Mid_Label END IFCONSTRUCT BY NAME s ON yAFTER FIELD yIF a[1] THEN EXIT FOR END IFIF a[1] THEN CONTINUE FOR END IFIF a[1] THEN EXIT FOREACH END IFIF a[1] THEN CONTINUE FOREACH END IFIF a[1] THEN EXIT WHILE END IFIF a[1] THEN CONTINUE WHILE END IFIF a[1] THEN RETURN END IFIF a[1] THEN EXIT MENU END IFIF a[1] THEN CONTINUE MENU END IF

-- EXIT INPUT is not allowed by the compiler (error 4488)-- IF a[1] THEN EXIT INPUT END IF-- CONTINUE INPUT is not allowed by the compiler-- (error 4488)-- IF a[1] THEN CONTINUE INPUT END IF

IF a[1] THEN EXIT CONSTRUCT END IFIF a[1] THEN CONTINUE CONSTRUCT END IFIF a[1] THEN GOTO End_Label END IF

IF a[1] THEN GOTO Mid_Label END IFCALL SET_COUNT(3)DISPLAY ARRAY a TO a.*

ON KEY (F3)IF a[1] THEN EXIT FOR END IFIF a[1] THEN CONTINUE FOR END IFIF a[1] THEN EXIT FOREACH END IFIF a[1] THEN CONTINUE FOREACH END IFIF a[1] THEN EXIT WHILE END IFIF a[1] THEN CONTINUE WHILE END IFIF a[1] THEN RETURN END IFIF a[1] THEN EXIT MENU END IFIF a[1] THEN CONTINUE MENU END IFIF a[1] THEN EXIT DISPLAY END IF

-- CONTINUE DISPLAY is not allowed by the compiler-- IF a[1] THEN CONTINUE DISPLAY END IF-- EXIT INPUT is not allowed by the compiler (error 4488)-- IF a[1] THEN EXIT INPUT END IF-- CONTINUE INPUT is not allowed by the compiler (error-- 4488)-- IF a[1] THEN CONTINUE INPUT END IF-- EXIT CONSTRUCT is not allowed by the compiler (error-- 4488)-- IF a[1] THEN EXIT CONSTRUCT END IF-- CONTINUE CONSTRUCT is not allowed by the compiler-- (error 4488)-- IF a[1] THEN CONTINUE CONSTRUCT END IF



IF a[1] THEN GOTO End_Label END IFIF a[1] THEN GOTO Mid_Label END IFINPUT ARRAY a FROM a.*AFTER FIELD yIF a[1] THEN EXIT FOR END IFIF a[1] THEN CONTINUE FOR END IFIF a[1] THEN EXIT FOREACH END IFIF a[1] THEN CONTINUE FOREACH END IFIF a[1] THEN EXIT WHILE END IFIF a[1] THEN CONTINUE WHILE END IFIF a[1] THEN RETURN END IFIF a[1] THEN EXIT MENU END IFIF a[1] THEN CONTINUE MENU END IFIF a[1] THEN EXIT INPUT END IFIF a[1] THEN CONTINUE INPUT END IF

-- EXIT DISPLAY *is* allowed by the compiler (despite-- error 4488)

IF a[1] THEN EXIT DISPLAY END IF-- CONTINUE DISPLAY is not allowed by the compiler-- IF a[1] THEN CONTINUE DISPLAY END IF-- EXIT CONSTRUCT is not allowed by the compiler (error-- 4488)-- IF a[1] THEN EXIT CONSTRUCT END IF-- CONTINUE CONSTRUCT is not allowed by the compiler-- (error 4488)-- IF a[1] THEN CONTINUE CONSTRUCT END IF

IF a[1] THEN GOTO End_Label END IFIF a[1] THEN GOTO Mid_Label END IFLABEL Mid_label:MESSAGE "You got here? How?"NEXT FIELD y

END INPUTEND DISPLAYEND CONSTRUCTEND INPUTCOMMAND "Z"MESSAGE "Sucker!"CONTINUE MENUEND MENUEND MENUEND WHILEEND FOR

END FOREACHLET y = 0

LABEL End_label: CLOSE WINDOW w

END FUNCTION


Precedence and Associativity of 4GL Operators

Notes on Nested and Recursive Operations

This section includes more information about nested and recursiveoperations.

■ Nested INPUT occurs when two INPUT-type statements (INPUT,INPUT ARRAY, DISPLAY ARRAY, or CONSTRUCT) operate concur-rently on the same fields in the same form. Concurrently, in thiscontext, means that an INPUT-type statement using a field issuspended while another INPUT-type statement uses the same field.

■ Opening and closing forms precludes nesting and recursion on thoseINPUT-type statements; nested and recursive input can only occurwhen forms are not being opened and closed while the outerstatement is still processing.

■ Recursive and nested input implies the use of the same 4GL window;changing the current window inherently changes the form (orinstance of the form) in use.

Recursive INPUT occurs when two instances of the same INPUT-typestatement operate concurrently, then a BEFORE or AFTER or ON KEY clausetakes control and invokes the function containing the same INPUT-typestatement recursively, re-executing that INPUT-type statement. It does notmatter whether the recursion was direct (the function calls itself) or indirect(the function calls another, which in turn calls the first function again).

Precedence and Associativity of 4GL OperatorsThe CLIPPED operator has a very low priority, which can lead to confusionwhen writing compound test conditions. For example, i4glc1 and fglpc bothparse the condition:

IF LENGTH(f2) > 0 AND f2 CLIPPED != "customer" THEN

as if it were bracketed as:

IF (((LENGTH(f2) > 0) AND f2) CLIPPED) != "customer" THEN

To achieve the required result, write the expression as:

IF LENGTH(f2) > 0 AND (f2 CLIPPED) != "customer" THEN


Using Segmented Form Fields with WORDWRAP

Using Segmented Form Fields with WORDWRAPThere are two methods that 4GL uses to break up long character fields informs: subscripted fields, and multiple-segment fields with WORDWRAP.

4GL has the ISQL form syntax for subscripting long character fields. However,4GL form statements (for example, CONSTRUCT, DISPLAY, INPUT) can accessonly the first segment of a multi-segment subscripted field; thus, subscriptedfields are not very useful.

If you use the record.* notation to denote all fields of the screen record, itcauses an error if a ISQL-style segmented field participates because eachsegment counts as a separate screen record item, making the counts conflictbetween the screen record and the 4GL form statement. Unfortunately, in thisrelease and all past releases of 4GL, default (generated) forms createsubscripted field references for all character-type columns which are greaterthan the screen width minus 22 columns in length. (For example, for a normal80-column form, character type columns greater than 58 characters longcause the default form generator to split the column into multiplesubscripted form fields, each no more than 58 characters long and of similarlength.)

ISQL-style segmented fields use unique field tags with subscripted dimen-sions, as the following example demonstrates:

screen ... char_len_59 [f002 ] [f003 ] ... attributes ... f002 = span.char_len_59[1,30]; f003 = span.char_len_59[31,59]; ...

In this case, 4GL could only use the first 30 characters of char_len_59 forINPUT or DISPLAY. This illustrates the disadvantage of using subscriptedfields.


WORDWRAP in REPORTS

The following code sample shows multiple-segment fields for use withWORDWRAP:

screen ... char_len_59 [f002 ] [f002 ] ... attributes ... f002 = span.char_len_59, WORDWRAP COMPRESS; ...

You can use the multiple-segment field in its entirety with the built-inmultiple-line editor. If you use generated forms that have fields based onlong character columns, you should convert the affected form fields to bemultiple-segment, WORDWRAP-compatible fields.

WORDWRAP in REPORTSIn earlier versions of RDS, the WORDWRAP attribute in reports did not yieldcorrect results. Any report that attempted to use a PRINT statement inconjunction with WORDWRAP could produce misaligned output (the outputbegan at the wrong column) and extra trailing spaces (the PRINT statementappeared to ignore the CLIPPED attribute even when it had been specified).

Now the WORDWRAP attribute in RDS produces correct results.


Left-justification of Numeric Form Fields

Left-justification of Numeric Form FieldsIn the earlier releases of 4GL, numeric values were right-justified in formfields. However, the ISQL form runner (sperform) always left-justifiednumbers unless you specified the attribute RIGHT for the field. Now it ispossible to specify the form field attribute COLOR=LEFT, but this attribute isignored at runtime. Right-justification of numeric values remain the defaultbehavior for 4GL, but the 6.01 and subsequent releases of 4GL honor theattribute COLOR=LEFT to force left-justification of numeric values. Thefollowing data types are affected:

■ DECIMAL

■ MONEY

■ INTEGER

■ SMALLINT

■ FLOAT

■ SMALLFLOAT

■ SERIAL

Using New REPORT/RUN/OPTION FunctionalityThe functionality changes described here relate to REPORT statements, RUNstatements, and OPTION statements. They use some shared new syntax.

New REPORT FunctionalityThere are several new statements you can use in a report and new syntax youcan use in existing statements.

RETURN statements are not allowed in reports (as they are functionallyambiguous, leaving reports in various stages of being opened or closeddepending on which control block uses the RETURN).

In its place is the new, reliable EXIT REPORT statement, which explicitly exitsand closes the report from within the report. You can also terminate a reportwhile not in the report using the statement TERMINATE REPORT.


New REPORT Functionality

Syntax

TERMINATE REPORT <report-name>EXIT REPORT

The START REPORT report-name TO report-destination statement and REPORTTO report-destination clause in the OUTPUT section of the report have bothbeen extended symmetrically in this release. The report-destination clause isnow:

<report-destination> ::= SCREEN | PRINTER | [ FILE ] <report-target> | PIPE [ <pipe-screen-mode> ] <report-target> <report-target> ::= <literal-string> | <string-variable>

<line-form-mode> ::= IN { LINE | FORM } MODE

<pipe-screen-mode> ::= <line-form-mode>

The changes are:

■ Explicit destination SCREEN (you can use it to override a defaultdestination going to somewhere else)

■ Optional (to retain backwards compatibility) keyword FILE for fileoutput

■ Optional mode for PIPE command, with the default being IN FORMMODE for backwards compatibility

Additionally, the ORDER BY clause in reports has been extended marginallyin this release. You can now specify internal sorting explicitly using theINTERNAL keyword. In the absence of either ORDER BY or INTERNAL,INTERNAL is the default for backwards compatibility.

<report-order-by-clause> ::= ORDER [ <sort-mode> ] BY <variable-list>

<sort-mode> ::= EXTERNAL | INTERNAL


New RUN Functionality

New RUN FunctionalityIn previous releases of 4GL, use of the RUN statement did not automaticallycause the screen to clear. The screen only cleared when the RUN code exitedfrom form mode, because the termcap entry for the terminal includes a clearscreen as part of the terminal reset capability.

The new functionality of the RUN statement gives you the choice of whetherto exit from form mode automatically or not exit form mode at all.

The extended RUN statement follows:

<run-statement> ::= RUN <command-specifier> [ <run-screen-mode> ]

[ <run-control-mode> ]

<command-specifier> ::= <literal-string> | <string-variable> <run-screen-mode> ::= <line-form-mode>

<run-control-mode> ::= WITHOUT WAITING | RETURNING <integer-variable>

New OPTION FunctionalityThe new REPORT functionality and the new RUN functionality resulted innew RUN and PIPE functionality for the OPTION statement:

<option-specifier> ::= [ ... ] | RUN <line-form-mode> | PIPE <line-form-mode>


RUN...RETURNING Clause

FORM MODE and LINE MODE

The default behavior for RUN is LINE MODE (the screen clears by default)because it is backwards compatible with the current behavior. This is theopposite of the default for PIPE. If the statement specifies an explicit screenmode, then that is used. If there is no explicit mode, then the prevailing valuefrom the OPTIONS statement is used. In LINE MODE, the terminal is in thesame state (stty options) as when the program began. This usually means thatthe terminal input is in cooked (rather than raw) mode, with interruptsenabled, and so on. In FORM MODE, the terminal is in raw mode, so eachcharacter is available to the program as it is read, rather than becomingavailable when the newline character is typed (cooked mode).

By default, I4GL programs operate in LINE mode, but so many statementstake it into FORM mode — including the OPTIONS statements that set keys,DISPLAY AT, OPEN WINDOW, DISPLAY FORM, and so on—that most I4GLprograms are actually in FORM most of the time. When the prevailing RUNoption specifies FORM MODE, the program remains in FORM MODE if itcurrently is FORM MODE, but it does not enter FORM MODE if it is currentlyin LINE MODE. When the prevailing RUN option specifies LINE MODE, theprogram remains in line mode if it is currently in LINE MODE, and it switchesto LINE MODE if it is currently in FORM MODE. The same comments apply tothe PIPE option.

RUN...RETURNING ClauseThe behavior of the value returned from a 4GL “RUN ... RETURNING” clauseis different on different machines. Because of OS limitations (see exit(2) orwait(2) in the UNIX Programmer's Manual), the exit status of a command canreturn a range of only 256 values. However, the operating system uses thelow order 8 bits of a 16-bit integer for its own information, and the 256 exitstatus values are stored in the high order 8 bits of the 16-bit integer.

When a 4GL INTEGER variable stores this 16-bit value, it treats this value asan unsigned quantity, whereas previously, depending on platform, it couldtreat this value as either signed or unsigned. If the status is stored in aSMALLINT, any exit status between 128 and 255 (an exit status of -1 is equiv-alent to 255) is stored as a negative number. For portability, always store thestatus of the command in an INTEGER. You need to divide the value saved by256 to get the actual exit status. The low order bits are only non-zero if anunexpected signal killed the shell that ran the command.


New C Functions: popstring( ) and retstring( )

New C Functions: popstring( ) and retstring( )This release of 4GL contains two new C functions, popstring( ) andretstring( ).

The function, popstring( ), has the same interface as popquote( ) (see Version6.0 of the INFORMIX-4GL Reference), but it returns the string with no trailingblanks.

The function retstring( ) provides symmetry only; retstring( ) callsretquote( ) internally.


4Chapter

The 4GL Compiler

Environment Variables . . . . . . . . . . . . . . . . . 4-3C4GLFLAGS and FGLPCFLAGS. . . . . . . . . . . . . 4-4C4GLNOPARAMCHK . . . . . . . . . . . . . . . . 4-4

Changes to the I4GL and C4GL Compilation System . . . . . . . 4-5 The Five-Phase I4GL Compilation Process . . . . . . . . . 4-6Shell Scripts for Backward Compatibility . . . . . . . . . . 4-7

Using the C4GL Script to Do Compilations . . . . . . . . 4-8The New -phase Option . . . . . . . . . . . . . . . . 4-8The New -keep and -nokeep Options . . . . . . . . . . . 4-9

The New -z Option . . . . . . . . . . . . . . . . 4-9The New -globcurs Option . . . . . . . . . . . . . 4-10

The INFORMIXC and CC Environment Variables . . . . . . . 4-11The C4GLFLAGS Environment Variable . . . . . . . . . . 4-12I4GL Libraries and Header Files Have Been Moved . . . . . . 4-12Number of Lines and Compiling . . . . . . . . . . . . . 4-13

Using Source Code Debuggers with I4GL Programs . . . . . . . 4-13

Shared Libraries . . . . . . . . . . . . . . . . . . . . 4-15Using the Shared Library Facility . . . . . . . . . . . . 4-16

Technical Details . . . . . . . . . . . . . . . . . 4-17Runtime Requirements . . . . . . . . . . . . . . . 4-18

4-2 INFO

his chapter describes the 4GL compiler and changes to it sincepublication of the Reference manual. This chapter includes the following:

■ Environment variables affecting the 4GL compiler

■ Changes to the I4GL and C4GL compilation system

■ Using source code debuggers with I4GL Programs

■ Shared libraries

Environment VariablesThe following environment variables affect the 4GL compiler:


■ C4GLNOPARAMCHK

These and other environment variables are described in detail in Chapter 7,“Environment Variables.”

T

The 4GL Compiler 4-3

C4GLFLAGS and FGLPCFLAGS

C4GLFLAGS and FGLPCFLAGSThe environment variables C4GLFLAGS and FGLPCFLAGS allow you to setcertain compiler options as defaults. These options simplify many compila-tions. Typical values are:

You should compile all 4GL programs with -anyerr specified. If your portsupports shared libraries, you should also use the -shared option.

C4GLNOPARAMCHKC4GLNOPARAMCHK is a new environment variable which, if set, turns offthe error checking on the number of arguments passed into a routine and onthe number of values returned from it. By default, these are now checked asstringently as in the p-code system.

The behavior of compiled 4GL has always been different from that of RDS inhow it checks the number of arguments passed to a function and the numberof values returned from a function. RDS requires the number of argumentspassed and the number of values returned to be correct. By default, I4GL nowchecks for the accuracy of the number of arguments and number of returnvalues, and generates a fatal error if they are incorrect. Any code whichworked under RDS, works with the new compiled code; only code which didnot work under the p-code system, fails. You can disable this checkingmechanism at compile time by setting the new environment variableC4GLNOPARAMCHK (the value does not matter but the variable must bepresent in the environment). You should not expect to use this environmentvariable, which will be removed in a future release, leaving the new default(strict checking) behavior as the only behavior.

-a C4GLFLAGS only

-ansi C4GLFLAGS and FGLPCFLAGS

-anyerr C4GLFLAGS and FGLPCFLAGS

-shared C4GLFLAGS only

-z C4GLFLAGS and FGLPCFLAGS


Changes to the I4GL and C4GL Compilation System

The following behavior occurs:

■ If the C4GLNOPARAMCHK environment variable is not set, allfunction calls and returns are checked, and a fatal error is generatedif there is a mismatch in the number of parameters passed orreturned.

■ If the C4GLNOPARAMCHK environment variable is set andAnyError Error Scope is not in effect, parameter count checking codeis not generated.

■ If the C4GLNOPARAMCHK environment variable is set andAnyError handling is in effect, and if the error action is CONTINUE,no parameter count checking is generated; for any other error actions(such as STOP, GOTO, CALL), the parameter count checking code isgenerated.

Changes to the I4GL and C4GL Compilation SystemVersions 6.00 and higher of I4GL compile 4GL source code differently fromprevious versions, in the following ways:

■ The five-phase I4GL compilation process

■ FGLC and FGLC2 shell scripts for backward compatibility

■ I4GL/PE always uses the C4GL script to do compilations

■ C4GL uses the new -phase option

■ C4GL uses the new -keep and -nokeep options

■ C4GL uses the new -z option

■ C4GL uses the new -globcurs option

■ C4GL uses the INFORMIXC and CC environment variables

■ C4GL uses the C4GLFLAGS environment variable

■ The I4GL libraries and header files have been moved

■ I4GLC4

These differences are detailed in the following sections.


The Five-Phase I4GL Compilation Process

The Five-Phase I4GL Compilation ProcessTo make I4GL independent of ESQL/C, the compilation sequence requires oneor more extra processes. A diagram shows the five compilation phases in theVersion 6.0 and higher compilation procedure. The five phases are:

1. The i4glc1 preprocessor converts a 4GL source file with .4gl extensioninto a file with .4ec extension. It parses the 4GL language andgenerates C code to handle function and report definitions, compu-tations, and function calls. It generates extended ESQL/C statementsto handle forms, menus, input statements, and display statements,and pure ESQL/C to handle SQL statements and variable declara-tions. i4glc1 is similar to Version 4.12 and earlier fglc, except thati4glc1 generates a .4ec file instead of a .ec file.

2. The i4glc2 preprocessor Version 4.12 and earlier translates theextended form, menu, input, and display statements to pure C codebut leaves variable declarations and SQL statements unchanged.i4glc2 accepts a .4ec file generated by i4glc1 as input and produces a.ec file containing pure ESQL/C.

3. The i4glc3 preprocessor is a copy of the standard 6.00 ESQL/Ccompiler. i4glc3 accepts a .ec file (produced by i4glc2 or written aspure ESQL/C), and produces a .c file. The declarations and the SQLstatements are mapped to pure C.

Figure 4-1The Five-Phase

CompilationProcess

∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠∠

i4glc1

\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \

file.4gl

file.4ec

\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \

file.ec

\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \

file.c

\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \\ \ \ \ \ \ \ \ \

file.c◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊◊file.o orfile.4ge

i4glc2i4glc3

i4glc4CC


Shell Scripts for Backward Compatibility

4. The i4glc4 preprocessor converts C code, which may containinternational characters in variable names, into de-internationalizednames. This step ensures that defining a record like table.* or a fieldlike table.column does not produce C code that contains interna-tional characters because very few C compilers accept thesecharacters in variable names.

5. Informix uses the system C compiler to convert the C code generatedby i4glc3 or i4glc4 into object files and executable programs.

Shell Scripts for Backward CompatibilityThe FGLC, FGLC2 and FGLC3 shell scripts provide backward compatibilitywith user scripts or makefiles that were designed for use with 4.12 and earlierversions of 4GL. Since the compilers fglc, fglc2, and fglc3 resided in$INFORMIXDIR/lib in Version 4.12, the new shell scripts replace them in thesame directory in the 6.0 I4GL product.

Because fglc converted a .4gl file into a .ec file, its function corresponds tothat of i4glc1 and i4glc2. The .ec file generated by FGLC is different from theone generated by fglc because the output of FGLC is a pure ESQL/C program,whereas the output from fglc contained extended ESQL/C statements such as$MENU, $DISPLAY, and $INPUT, which now only appear in .4ec files.

Similarly, fglc2 converted an (extended) ESQL/C file into a pure C file thatcorresponded to those of i4glc3 and i4glc4. The difference is that the .ec filein 4.12 contained a mixture of forms statements and ESQL/C statements,whereas in 6.0 the .ec file is pure ESQL/C. The script FGLC2 executes C4GLwith the argument -phase 34 to perform the steps i4glc3 and i4glc4 forproducing a .c file.

Finally, the script fglc3 simulates the converter fglc3 provided by releases4.12 and higher.


The New -phase Option

Using the C4GL Script to Do Compilations

Prior to Version 4.12, I4GL/PE used built-in knowledge about whatcommands need to be executed to convert a .4gl file into a .ec file, a .ec fileinto a .c file, and a .c into a .o file or executable file. This included details suchas the list of library names and special options.

With the advent of Version 6.0 servers, the 6.0 version of I4GL takes intoaccount that the database, table and column names might contain interna-tional characters. Most C compilers do not accept these in variable names, butthe i4glc4 process now maps the international characters so that C compilerswill accept them.

To simplify the changes required and to simplify the code stream so that thereis no difference between current releases of the 4.1 and 6.0 versions of 4GL,the compilation scheme was revised so that I4GL/PE invokes C4GL to do thecompilation, using the -phase option described in the following section.

I4GL/PE now runs c4gl -phase 12 (i4glc1 and i4glc2) as its own phase 1,followed by c4gl -phase 34 (i4glc3 and i4glc4) as its own phase 2, and finallyit runs c4gl -phase 5 (the C compiler) as its own phase 3.

There has never been a facility to let you specify array bounds checking(using the -a flag) for compilations done using I4GL/PE. However, becausethe C4GL script is used for the compilations, you can also use the C4GLFLAGSenvironment variable (see “The C4GLFLAGS Environment Variable” onpage 4-12) with I4GL/PE.

The New -phase OptionC4GL has some new options supporting the new behavior of I4GL, with theold behavior as the default.

C4GL now recognizes the five phases of compilation. A new option, -phase,takes an argument separated from -phase by one or more spaces. Thisargument can contain any contiguous sequence of numbers between 1 and 5(that is, 1, 2, 3, 4, 5, 12, 23, 34, 45, 123, 234, 345, 1234, 2345, 12345), with thedefault being 12345. The older -e option has been retained and correspondsto -phase 1234. The old -c option implies -phase 12345, but the C compileronly generates the object files and does not link them to produce anexecutable.


The New -keep and -nokeep Options

The New -keep and -nokeep OptionsC4GL automatically removes the intermediate files—the .c, the .ec, and the.4ec files—that it generates when the compilation completes successfully.This is a change from earlier versions. If the compilation fails or is inter-rupted, then all the intermediate files are left intact.

The new -keep option explicitly specifies that the intermediate files beretained. The 6.0 default is the -nokeep option which specifies that the inter-mediate files be removed. The .o file is retained if you specify the -c flag.However, if an executable is produced, the .o file is kept or removeddepending on the C compiler in use. Some keep the .o file, others remove itdepending on what other files you specify on the command line. If you directthe script to do -phase 1234, the .c file is no longer an intermediate file and isretained. Similarly, if you request phase 1, the .4ec is no longer an interme-diate file and is kept. The system deletes intermediate files only if thecompilation is successful.

The New -z Option

The -z option lets C4GL invoke a single function with a variable number ofarguments without i4glc1 giving an error at compile time.

Although the 6.0 release of fglc supported the -z option, the C4GL shell scriptignored the option, so it was not possible to use the standard script to compileprograms with such functions. It is not advisable to use this option becauseit suppresses error messages for all functions with variable numbers ofarguments, although there are generally very few (if any) of these functionsin a program.


The New -keep and -nokeep Options

The New -globcurs Option

In I4GL and ESQL/C releases prior to Version 4.13, all cursor and statementnames are local to a single file, and reusing the same name in different filesdoes not cause problems. In Versions 5.0 and 6.0 ESQL/C, all cursor andstatement names are global by default. This means that the cursor c_query infilea.ec is the same as the cursor c_query in fileb.ec. To preserve the oldbehavior in both I4GL and RDS, the compiler mangles all cursor andstatement names using the same algorithm in both compilers. The mangledname is always 18 characters long. The first half is derived from the inodenumber of the 4GL source file, and the second half is derived from the user-supplied name, using the hashing algorithm shown in the following codeexample. Rarely, two distinct names in the same file may end up with thesame hashed name, which could lead to a variety of problems. The algorithmis documented here so that if you run into problems, you can diagnose whatthe trouble is. Let Informix Technical Support know of any pairs of cursor orstatement names that are mangled to the same value. The workaround is tochange one of the affected cursor or statement names.

The new -globcurs option lets you make the cursors global to the entireprogram. However the compilers still require you to declare the cursor beforeusing it for any other purpose in the module, so this option is seldom useful.However, it may help in debugging, because the cursor names are notmodified. You can also use -globcurs with FGLPC.


The INFORMIXC and CC Environment Variables

I4GL and RDS both use the same cursor name hashing scheme. The followingcode hashes a cursor name:

...sprintf(mangled_name, "I%08X_%08X", inode_number,

hash_cursorname(cursor_name));

...

static unsigned long hash_cursorname(name)char *name;{

unsigned long uhash = 0x14C1BC85;unsigned long g;unsigned char *s;unsigned char c;

for (s = (unsigned char *)name; (c = *s) != '\0'; s++){

uhash = (uhash << 4) + (c);if ((g = uhash & 0xF0000000L) != 0){

uhash = uhash ^ (g >> 24);uhash = uhash ^ g;

}}return(uhash);

}

The cursor-name-mangling scheme makes it difficult for an ESQL/C moduleto use cursors or statements from an I4GL module. Since it was impossible toshare the cursors in 4.0 and 4.1, existing code is not affected. Version 6.0 4GLstill works in terms of 4.0 and 4.1 rules, so you cannot create cursors in one4GL module and reference them in another.

The INFORMIXC and CC Environment VariablesC4GL uses the INFORMIXC and CC environment variables (defaulting to cc onmost machines) in the final stage of compilation. Setting one of theseenvironment variables lets you substitute any C compiler. Because CC isacknowledged by many versions of MAKE, this environment variable iscompatible with other programs also. You use the following Bourne shellcode to determine the compiler:

${INFORMIXC:=${CC:-cc}}


The C4GLFLAGS Environment Variable

Thus, for the compiler, use the value of an INFORMIXC environment variablethat is not empty; if there is no non-empty INFORMIXC environmentvariable, use the (non-empty) value of the CC environment variable; if neitherof those exist, default to cc.

Important: For users of GCC: Informix assumes that strings are writable, so youneed to compile using the -fwritable-strings option. Failure to do so causes unpre-dictable results, possibly including core dumps.

The C4GLFLAGS Environment VariableC4GL acknowledges the C4GLFLAGS environment variable, which allowsyou to set certain compiler options as defaults. You can specify the flags-keep, -a, and -ansi, and all compilations occur as specified in C4GLFLAGS.

Do not specify -phase, -e, or -c (or, for the C compiler, -P, -E, or -S) in thisenvironment variable as it prevents the compilations from completing. Forexample, if you specify -e in the C4GLFLAGS environment variable, thesystem always stops compiling after producing a .c file; it does not produceobject or executable files.

I4GL Libraries and Header Files Have Been MovedThe I4GL libraries and header files reside in new directories and are separatefrom the libraries and header files that ESQL/C uses, even though thecommon files are identical. All the libraries that the Version 6.0 family of toolsuses reside in the $INFORMIXDIR/lib/tools directory. Similarly, all the headerfiles that the Version 6.0 tools family uses are in the$INFORMIXDIR/incl/tools directory. The compilers i4glc1, i4glc2, i4glc3, andi4glc4 are in the $INFORMIXDIR/lib/tools directory, whereas the older fglc,fglc2, and fglc3 files (and their contemporary shell script replacements)remain in $INFORMIXDIR/lib.


Number of Lines and Compiling

If you explicitly list the headers from the Informix directories in the depen-dency lines in your makefiles, then you need to modify the dependency lines.Also, if the makefiles explicitly list the libraries to be linked, then you mustchange those lists since not only are the libraries in a different directory, butboth the number and the names of the libraries have changed. Alternatively,if you do not list the I4GL libraries but simply use C4GL to do the linking, thenno change is needed. C4GL has been, and continues to be, portable acrossreleases. The most reliable way to compile a .4gl file to an object file is usingc4gl -c. Similarly, the most reliable way to link a program is using c4gl -o.

Number of Lines and CompilingANSI C compilers are required to warn about #line numbers generated fromthe compilation that are greater than 32767. This can happen in compiled 4GLwhen the underlying ESQL/C compiler works on a large program.

Now, you can suppress these warnings through the C4GL script using thenew -nolinenos option, which you can set via the C4GLFLAGS environmentvariable. You can also explicitly set the default ANSI action, generation ofwarnings, with the -linenos option.

Using Source Code Debuggers with I4GL ProgramsThis section pertains to using source-code debuggers with I4GL programs.The primary conversion of i4glc4 ensures that the generated C code willcompile when you use I4GL with an NLS database. In an NLS database, thetable and column names can contain non-ASCII characters ranging from 128to 255. You can define variables using the RECORD LIKE Table.* to refer tothese names, but C compilers do not normally allow variable names tocontain such characters. To avoid compilation problems with the C compiler,I4GLC4 adjusts the code.


Using Source Code Debuggers with I4GL Programs

To make the variable names safe, Informix replaces any non-ASCII charactersthat occur outside quoted strings (which only happens in variable or functionnames) with a mapped value. For values in the range 0xA0 to 0xFF, Informixuses the hexadecimal value, printed in uppercase, for the character. Thesystem maps characters in the range 0x80 to 0x8F, to G0 to GF, and values inthe range 0x90 to 0x9F, to H0 to HF. The system converts all ordinary I4GLidentifier names to lowercase to avoid a naming conflict. By the time thistranslation occurs, the names of tables and columns in SQL statements are notaltered; quotes protect the names passed to the server. The i4glc4 compilerdoes one other translation, and that only inside strings: it converts y-umlaut(hex 0xFF) into the escape sequence \377. This is because some C compilersare not fully internationalized and read this character as EOF.

Tip: The p-code compiler, FGLPC, does not do this mapping.

Using the ESQL/C compiler for phase 3 introduces yet another complicationto the compilation process. 4GL uses a different view of the SQLCA recordfrom ESQL/C: the warning flags are a series of single characters in ESQL/Cbut 4GL code treats them as a string. The ESQL/C compiler automaticallyincludes the sqlca.h header ahead of any user-defined code such as the I4GLdeclaration of the SQLCA record. This would lead to two discrepant defini-tions of the SQLCA record, and the compilations would fail, unless the C4GLscript handled this. To overcome this problem, i4glc1 emits a line that starts#define I4GL_SQLCA just before the declaration of the SQLCA record. Thei4glc2 and i4glc3 compilers pass this through. If the .c file to be processed byi4glc2 contains this definition but does not contain the line #defineSQLCA_INCL, then C4GL passes an extra flag to i4glc4 and adds the line#define SQLCA_INCL in front of the C file it translates. The C preprocessorhandles this so that the contents of the sqlca.h header are ignored, leavingjust the I4GL version of the SQLCA record visible to the C compiler.

You can use i4glc4 on its own. It takes the following arguments:

-V prints version information (does not process any files).

-D emits #define SQLCA_INCL as the first line of output.

-s ext creates backup file with the extension .ext.

-o overwrites input files.


Shared Libraries

By default, i4glc4 writes the converted file or files to standard output, but youcan overwrite the original file using the -o option; you can back up theoriginal file with any extension you choose. There is no default extension.The i4glc4 compiler automatically inserts a . between the name and theextension. The -o and -s options are mutually exclusive and require afilename argument. Otherwise, i4glc4 processes any files specified, orprocesses standard input if no filenames are provided.

Shared LibrariesEffective with the Version 6.0 release of (compiled) 4GL, a shared libraryimplementation of the 4GL program libraries is provided on many platforms.The shared library provides reduced memory consumption, faster programstart-up, and reduced program file sizes (thereby saving file system space).

Shared library support exists for compiled 4GL only. ISQL and 4GL RDSrunners (fglgo or custom runners) are inherently shared because all activeusers run the same executable file. This feature is most useful for those instal-lations that have a variety of compiled 4GL applications: the 4GL library codeexists in only one place in memory and does not have to be added to each 4GLexecutable file. On a system with a large number of 4GL programs, the diskspace and memory savings can be substantial.

Informix does not provide a shared library implementation on all platforms.On some platforms, shared libraries are not available and on others theoperating system implementation of shared libraries is not compatible withthe Informix code stream.

To determine if your platform has a shared library implementation of 4GL,look at the C4GL help messages. You can display these by running c4gl withno arguments. A help line for the shared option contains one of thesemessages:

-shared Use dynamic linking and shared libraries

or:

-shared (Not available on this platform)


Using the Shared Library Facility

If the former message is the one given for your platform, then a 4GL SharedLibrary implementation is provided, and the -shared option is available foryour use.

You can demonstrate the memory and file-size savings for your platform bycompiling the 4GL demonstration program (demo4) with and without the-shared flag, and comparing the outputs of ls and size for each of thefollowing programs:

■ i4gldemo

■ c4gl -shared d4_*.4gl -o demo4.shared

■ c4gl d4_*.c -o demo4

■ ls -l demo4*

■ size demo4*

Some platforms provide commands that show the dependencies of acompiled program on the shared libraries. For instance, on current Sunplatforms, the command is ldd.

For more technical information about shared library concepts refer to youroperating system documentation. If your system has man pages (on-linemanuals), the man page for ld might direct you to the appropriate area ofyour system documentation.

Using the Shared Library FacilityTo compile a 4GL program for shared library execution, add the -sharedparameter to your C4GL command line:

c4gl -shared d4_*.4gl -o demo4.shared

If you attempt to use the -shared option on a platform for which no sharedlibrary support exists, a warning message is displayed to standard error, andcompilation continues with the normal static libraries.

Many platforms require that dynamically linked (shared library) programsbe compiled with position-independent code production from the Ccompiler. The C4GL script automatically takes care of this for you.



Mixing normal and position-independent code can produce errors. Whenyou compile with the -shared flag, be sure to recompile all modules from the.4gl source if you had previously compiled any without the -shared flag.

Consider the following example:

c4gl myprog.4gl myutil1.4gl myutil2.4gl -o myprogc4gl -shared myprog.o myutil1.o myutil2.o -o myprog.shared

Executing this code can produce errors because the objects have not beencompiled with the position-independent option. Alternatively, the followingcode is perfectly acceptable, as the myutil objects have been compiled withposition-independent code (if applicable to your platform):

c4gl -shared myprog.4gl myutil1.4gl myutil2.4gl -omyprog.shared <change myprog.4gl>c4gl -shared myprog.4gl myutil1.o myutil2.o -o myprog.shared

Tip: For some platforms, the system linker (ld) enforces much stricter name collisionconstraints when you use shared libraries. If you have multiple functions in yourprogram with the same name, you might get errors when compiling with sharedlibraries even if the program links successfully with the static libraries. In such a case,to eliminate the name collision you need to rename one of the functions.

Technical Details

The name and location of the 4GL shared library varies depending on theversion of 4GL you are using, the naming convention for shared libraries onyour platform, and the ability of the linker on your platform to locate sharedlibraries in nonstandard directories. The name of the shared library beginswith lib4gsh and continues with a three-digit version indicator (for example,604 for the 6.04 release). The suffix is platform-dependent; common valuesare .so and .a.



In most cases, the 4GL shared library resides with the other 4GL libraries inthe $INFORMIXDIR/lib/tools directory. If your platform does not allowshared libraries in nonstandard directories, your system administrator mighthave to copy the library to a standard system directory such as /lib or/usr/lib. Look in the machine-specific notes for your platform to see if this isnecessary. Most, if not all, platforms require that any programs that changetheir user ID dynamically while running (often referred to as setuid programs)and use shared libraries can only access those shared libraries in standardsystem directories. Therefore, if you have a setuid 4GL program that uses the4GL shared library, your system administrator must copy or link the 4GLshared library to a standard directory.

Runtime Requirements

Unlike static-linked I4GL programs, I4GL programs that use the sharedlibrary must have access to that library at runtime. Most platforms providean environment variable that instructs the operating system's linkingprogram loader to add one or more nonstandard directories to its sharedlibrary search list. Common examples of this variable areLD_LIBRARY_PATH, LPATH or SHLIB_PATH. The machine-specific notesprovided with I4GL contain the appropriate variable name for your platform.To run your shared library I4GL applications, you must have this variable setproperly in its shell environments. For example:

Bourne or Korn Shells

LD_LIBRARY_PATH=$INFORMIXDIR/lib/toolsexport LD_LIBRARY_PATH

C Shell Variants

setenv LD_LIBRARY_PATH ${INFORMIXDIR}/lib/tools

Be sure that all potential users set their environments accordingly or updateglobal environment scripts as applicable for their site.

If you develop 4GL applications that are sent out to other systems, the sharedlibrary must be available to those systems also. All platforms that have 4GLshared library support also have the 4GL shared library included in corre-sponding runtime versions of 4GL. Be sure to notify your remote users andruntime customers of these environment variable needs.


5Chapter

4GL Function Libraries

ORD( ) . . . . . . . . . . . . . . . . . . . . . . . 5-4

CURSOR_NAME( ). . . . . . . . . . . . . . . . . . . 5-5

Variables in Global Scope. . . . . . . . . . . . . . . . . 5-7

5-2 INFO

R elease 6.0 of 4GL provides two new built-in functions:

■ ORD( )

■ CURSOR_NAME( )

This chapter describes these functions, and also contains a section aboutvariables in global scope.

4GL Function Libraries 5-3

ORD( )

ORD( )This function evaluates the first character of a passed character stringargument as the corresponding integer number.

Syntax

ORD (string-expr)

4GL only evaluates the first character of the passed string.

Important: The string-expr requires parentheses.

ExampleThe following assignment assigns the value 66 to the integer ord1.

LET ord1 = ORD ("Belladonna")

ORD is a required keyword.

string-expr is a string expression.


CURSOR_NAME( )

CURSOR_NAME( )The built-in function CURSOR_NAME( ) provides a solution for the situationwhen name mangling for cursors does not work with UPDATE and DELETEstatements. The function CURSOR_NAME( ) mangles the cursor name,supplied as a string argument, in the same way as the compiler does. See“Changes to the I4GL and C4GL Compilation System” on page 4-5.

The problem occurs in the following situation:

DECLARE c_name CURSOR FOR SELECT ... FOR UPDATEPREPARE p_update FROM

"UPDATE SomeTable SET SomeColumn = ? WHERE CURRENT OF c_name"

The cursor name, c_name, is mangled into something likeI01234567_87654321, but the name embedded in the UPDATE statement is notmangled. This leads to a -507 error when the p_update statement is executed.

The new built-in function CURSOR_NAME( ) provides the solution to this bymangling names before they are embedded in the string; for example:

DECLARE c_name CURSOR FOR SELECT ... FOR UPDATELET s = "UPDATE SomeTable SET SomeColumn = ? WHERE CURRENT OF ",

CURSOR_NAME("c_name")PREPARE p_update FROM s

The name-mangling code uses, and therefore needs to know, the inodenumber of the source file at the time it is compiled. The fglpc and i4glc1compilers arrange for the inode number to be pushed onto the 4GL stackbefore the C function is called. This is invisible to the 4GL programmer.Although the CURSOR_NAME( ) function is of no use to the C programmer, itmust be called with two arguments on the 4GL stack, the inode number andthe name to be mangled.


CURSOR_NAME( )

An example of the CURSOR_NAME( ) function follows.

MAIN

DEFINE x CHAR(40) DEFINE y CHAR(40) DEFINE n INTEGER DEFINE s CHAR(100)

WHENEVER ANY ERROR CONTINUE DROP DATABASE b31661 WHENEVER ANY ERROR STOP

CREATE DATABASE b31661 CREATE TABLE b31661 ( col01 INTEGER NOT NULL ) INSERT INTO b31661 VALUES (1)

LET y = "some_name" LET x = CURSOR_NAME(y) DISPLAY x CLIPPED CALL CURSOR_NAME(y) RETURNING x DISPLAY x CLIPPED DECLARE some_name CURSOR FOR

SELECT col01 FROM b31661 FOR UPDATE LET s =

"UPDATE b31661 SET col01 = -1 WHERE CURRENT OF ", x PREPARE p_update FROM s FOREACH some_name INTO n EXECUTE p_update DISPLAY "UPDATE executed OK" END FOREACH

CLOSE DATABASE DROP DATABASE b31661

DISPLAY "Program complete"

END MAIN


Variables in Global Scope

Variables in Global ScopeAvoid using system function names (for example, read, open, stat) as namesfor global variables. Because 4GL does not check for the name conflictsbetween global variables and system function calls, errors can occur at runtime.


6Chapter

4GL Statement Syntax

CASE . . . . . . . . . . . . . . . . . . . . . . . 6-6

CONSTRUCT. . . . . . . . . . . . . . . . . . . . . 6-9The BY NAME Keywords . . . . . . . . . . . . . . . 6-14The ON Clause . . . . . . . . . . . . . . . . . . . 6-15The FROM Clause . . . . . . . . . . . . . . . . . . 6-16The ATTRIBUTE Clause. . . . . . . . . . . . . . . . 6-17The HELP Clause . . . . . . . . . . . . . . . . . . 6-19The BEFORE CONSTRUCT Clause . . . . . . . . . . . . 6-20The AFTER CONSTRUCT Clause . . . . . . . . . . . . 6-20The BEFORE FIELD Clause . . . . . . . . . . . . . . 6-21The AFTER FIELD Clause . . . . . . . . . . . . . . . 6-22The ON KEY Clause . . . . . . . . . . . . . . . . . 6-22The NEXT FIELD Statement . . . . . . . . . . . . . . 6-24The CONTINUE CONSTRUCT Statement . . . . . . . . . 6-26The EXIT CONSTRUCT Statement . . . . . . . . . . . . 6-27The END CONSTRUCT Statement . . . . . . . . . . . . 6-27AUTONEXT Ignored by CONSTRUCT . . . . . . . . . . 6-27Using WORDWRAP in CONSTRUCT . . . . . . . . . . . 6-27Using Functions in a CONSTRUCT Statement . . . . . . . . 6-33Interrupts in a CONSTRUCT Statement . . . . . . . . . . 6-35Strings Produced by a CONSTRUCT Statement . . . . . . . 6-35Behavior of CONSTRUCT and get_fldbuf() . . . . . . . . . 6-36

FOREACH. . . . . . . . . . . . . . . . . . . . . . 6-40

GLOBALS . . . . . . . . . . . . . . . . . . . . . . 6-44Variables in Global Scope . . . . . . . . . . . . . . . 6-45

6-2 INFO

INPUT . . . . . . . . . . . . . . . . . . . . . . . 6-46The BY NAME Clause . . . . . . . . . . . . . . . . 6-50The WITHOUT DEFAULTS Clause . . . . . . . . . . . . 6-51The FROM Clause . . . . . . . . . . . . . . . . . . 6-52The ATTRIBUTE Clause . . . . . . . . . . . . . . . . 6-52The HELP Clause . . . . . . . . . . . . . . . . . . 6-54The BEFORE INPUT Clause . . . . . . . . . . . . . . 6-55The AFTER INPUT Clause . . . . . . . . . . . . . . . 6-55The BEFORE FIELD Clause. . . . . . . . . . . . . . . 6-56The AFTER FIELD Clause . . . . . . . . . . . . . . . 6-57The ON KEY Clause . . . . . . . . . . . . . . . . . 6-57The NEXT FIELD Statement . . . . . . . . . . . . . . 6-59The CONTINUE INPUT Statement . . . . . . . . . . . . 6-60The EXIT INPUT Statement . . . . . . . . . . . . . . 6-61The END INPUT Statement . . . . . . . . . . . . . . 6-61WORDWRAP in INPUT . . . . . . . . . . . . . . . . 6-61AFTER INPUT Control Block . . . . . . . . . . . . . . 6-62Using Functions in an INPUT Statement . . . . . . . . . . 6-62Editing During an INPUT Statement . . . . . . . . . . . 6-65Completing an INPUT Statement. . . . . . . . . . . . . 6-65

INPUT ARRAY . . . . . . . . . . . . . . . . . . . . 6-68The WITHOUT DEFAULTS Clause . . . . . . . . . . . . 6-73The FROM Clause . . . . . . . . . . . . . . . . . . 6-74The HELP Clause . . . . . . . . . . . . . . . . . . 6-74The ATTRIBUTE Clause . . . . . . . . . . . . . . . . 6-74The BEFORE INPUT Clause . . . . . . . . . . . . . . 6-76The BEFORE ROW Clause . . . . . . . . . . . . . . . 6-77The BEFORE INSERT Clause . . . . . . . . . . . . . . 6-77The BEFORE DELETE Clause . . . . . . . . . . . . . . 6-78The AFTER INPUT Clause . . . . . . . . . . . . . . . 6-78The AFTER ROW Clause . . . . . . . . . . . . . . . 6-79The AFTER INSERT Clause. . . . . . . . . . . . . . . 6-79The AFTER DELETE Clause . . . . . . . . . . . . . . 6-80The BEFORE FIELD Clause. . . . . . . . . . . . . . . 6-80The AFTER FIELD Clause . . . . . . . . . . . . . . . 6-81The ON KEY Clause . . . . . . . . . . . . . . . . . 6-82


The NEXT FIELD Statement . . . . . . . . . . . . . . . 6-84The CONTINUE INPUT Statement . . . . . . . . . . . . 6-85The EXIT INPUT Statement . . . . . . . . . . . . . . . 6-86The END INPUT Statement . . . . . . . . . . . . . . . 6-86AFTER INPUT Control Block . . . . . . . . . . . . . . 6-86Using Functions in an INPUT ARRAY Statement . . . . . . . . 6-88Positioning the Cursor and Scrolling . . . . . . . . . . . . 6-90Inserting and Deleting Rows . . . . . . . . . . . . . . . 6-90Editing During an INPUT ARRAY Statement . . . . . . . . . 6-91Completing an INPUT ARRAY Statement . . . . . . . . . . 6-91

LOAD Statement Transaction Management . . . . . . . . . . . 6-94

MENU . . . . . . . . . . . . . . . . . . . . . . . . 6-98The BEFORE MENU Clause . . . . . . . . . . . . . . . 6-102The COMMAND Clause . . . . . . . . . . . . . . . . 6-102The KEY Clause . . . . . . . . . . . . . . . . . . . 6-103The HELP Statement . . . . . . . . . . . . . . . . . 6-103The CONTINUE MENU Statement . . . . . . . . . . . . 6-103The EXIT MENU Statement . . . . . . . . . . . . . . . 6-104The NEXT OPTION Statement . . . . . . . . . . . . . . 6-104The SHOW OPTION and HIDE OPTION Statements . . . . . . 6-105The END MENU Statement . . . . . . . . . . . . . . . 6-106Choosing a Menu Option . . . . . . . . . . . . . . . . 6-106Using Variables in a MENU Statement . . . . . . . . . . . 6-108Keys in a Command Key Clause . . . . . . . . . . . . . 6-111MENU COMMAND KEY Conflicts . . . . . . . . . . . . 6-111

Implications for Users Upgrading From Earlier Releases . . . . 6-112

PROMPT . . . . . . . . . . . . . . . . . . . . . . . 6-113OPTIONS PROMPT LINE Default Behavior . . . . . . . . . 6-113

UNLOAD . . . . . . . . . . . . . . . . . . . . . . 6-115

4GL Statement Syntax 6-3

6-4 INFO

his section includes reference information for all of the enhancedstatements. Release 6.0 of 4GL provides enhancements to the followingstatements:

■ CASE

■ CONSTRUCT

■ FOREACH

■ GLOBALS

■ INPUT

■ INPUT ARRAY

■ LOAD

■ MENU

■ PROMPT

■ UNLOAD

The descriptions of the statements in this supplement supersede thedescriptions of the previously listed statements in the INFORMIX-4GLReference Version 6.0.

T


CASE

CASEUse the CASE statement to select a sequence of statements, depending on thecurrent value of an expression.

SyntaxVariant 1:

CASEWHEN Boolean-expr

statement ...[EXIT CASE]...

WHEN Boolean-expr2statement...[EXIT CASE]...

...[OTHERWISE]

statement...[EXIT CASE]...

END CASE


CASE

Variant 2:

CASE (expr)WHEN expr1

statement...[EXIT CASE]...

WHEN expr2statement...[EXIT CASE]...

...[OTHERWISE]

statement...

[EXIT CASE]...

END CASE

Notes1. The CASE statement is equivalent to a set of nested IF statements.

2. If you use the OTHERWISE option, it must be the last in the list.

CASE is a required keyword.

expr, expr1,expr2

are expressions (or variables) of the same data type. Allowabledata types are CHAR, DECIMAL, INTEGER, SMALLINT, DATE,DATETIME, or INTERVAL.

WHEN is a required keyword.

Boolean-expr is a Boolean expression that is either TRUE or FALSE.

statement is a 4GL statement.

EXIT CASE is an optional statement that causes program control to pass tothe statement following the END CASE keywords.

OTHERWISE is an optional keyword introducing a sequence of statementsto be executed if none of the WHEN clauses is executed.

END CASE are required keywords that terminate the CASE statement.


CASE

3. When you use Variant 2 syntax, if you erroneously specify a Booleanexpression in a WHEN clause, the compiler may not detect the error,and the runtime result will probably be different than you expect. IfBoolean expressions are to be used, use only Variant 1 syntax.

4. There is an implied EXIT CASE statement at the end of each sequenceof statements following a WHEN clause. Program control will pass tothe sequence of statements following the END CASE statement.

5. Although both 4GL compilers (C4GL and FGLPC) accept CASE state-ments with WHEN clauses of the following form, do not use these asthey produce a false result.

To produce the correct result, use the following code, and reduce it tothe minimum possible, typically by calling a function.

CASE variableWHEN "A" -- code --WHEN "B" -- code --

ExampleLABEL question:

...CASE

WHEN answer MATCHES “[Yy]”CALL process()

WHEN answer MATCHES “[Nn]”CALL abort()

OTHERWISECALL retry()

END CASE

Related StatementsIF, EXIT

CASE Statement Translated to:

CASE variableWHEN “A” OR “B”

if (variable == (“A” or “B”))

CASE variableWHEN (variable = “A”OR variable = “B”)

if (variable == (variable == “A”or variable == “B”))


CONSTRUCT

CONSTRUCTThe CONSTRUCT statement updates a character variable to contain a Booleanexpression for use in the WHERE clause of an SQL statement (usually theSELECT statement). The Boolean expression is based on the query you specifyon the screen form.

Syntax

CONSTRUCT{

BY NAME char-variable ON column-list|char-variable ON column-list FROM

{field-list | screen-record [[n]].*} [, ...]}[ATTRIBUTE (attribute-list)] [HELP help-number][

{{

BEFORE CONSTRUCT|AFTER CONSTRUCT|BEFORE FIELD field-list|AFTER FIELD field-list|ON KEY(key-list)

}{

statement|NEXT FIELD { field-name | NEXT | PREVIOUS }|CONTINUE CONSTRUCT|EXIT CONSTRUCT

} ...} ...END CONSTRUCT

]


CONSTRUCT

CONSTRUCT is a required keyword.

BY NAME are optional keywords used to instruct 4GL to match names ofdatabase columns to screen field names.

char-variable is a character program variable that will contain the selectioncriteria.

ON is a required keyword used to specify the database columns.

column-list is a list of one or more database column names, separated bycommas. You can use the table-name.* syntax to refer to allcolumns in table-name.

FROM is an optional keyword used to specify screen fields for userentry of search values.

field-list is a list of one or more screen field names.

screen-record is the identifier of a collection of field names defined in a formspecification as a screen record.

[ n ] is an integer or integer variable, enclosed in brackets, speci-fying the row in a screen array in which the CONSTRUCT takesplace.

HELP is an optional keyword used to indicate the help message forthe statement.

help-number is an integer that identifies the help message for thisCONSTRUCT statement. You must have used the OPTIONSstatement previously to identify the help file containing themessage.

ATTRIBUTE is an optional keyword used to specify the screen displayattributes.

(attribute-list) is a list (in parentheses) of one or more screen displayattributes, separated by commas.

BEFORECONSTRUCT

is an optional clause containing one or more 4GL statements.4GL will execute these statements after first filling all the fieldslisted in the CONSTRUCT statement with blanks.

(1 of 3)


CONSTRUCT

AFTERCONSTRUCT

is an optional clause containing one or more 4GL statements.4GL executes these statements after you press the Accept key(unless you terminate the CONSTRUCT with the Interrupt orQuit key or a runtime error occurs) and before constructing theoutput string containing the Boolean expression.

BEFOREFIELD

is an optional clause containing one or more 4GL statements.4GL executes these statements each time you move the cursorinto the specified field or fields and before you enter selectioncriteria into the field.

AFTERFIELD

is an optional clause containing one or more 4GL statements.4GL executes these statements each time you move the cursorout of the specified field or fields, or when you press theAccept key while in the field.

ON KEY is an optional clause containing one or more 4GL statements.4GL executes these statements each time you press one of thekeys specified in key-list.

4GL preserves the contents of a field and the cursor locationwithin the field and resumes the CONSTRUCT after runningthe ON KEY statements. A DISPLAY statement can appear inthe ON KEY clause and change the contents of a field’s buffer.In this case, 4GL positions the cursor after the last non-blankcharacter in the field when it resumes the CONSTRUCTstatement.

key-list is one or more of the following, separated by commas:

■ F1 through F64

■ CTRL-char, where char is a letter

■ UP, DOWN, LEFT, RIGHT, NEXTPAGE, PREVPAGE, INSERT,

DELETE, ACCEPT, ESCAPE, ESC, INTERRUPT, HELP, TAB, orRETURN

For specific limitations on key-list, see the section titled “TheON KEY Clause” on page 6-22.

(2 of 3)


CONSTRUCT

PrerequisitesYou must first execute an OPEN FORM statement and a DISPLAY FORMstatement, or an OPEN WINDOW statement with the WITH FORM clause,before you can execute the CONSTRUCT statement. If you include a HELPclause, you must execute the OPTIONS statement and identify the help file.

statement is any 4GL statement. This can include NEXT FIELD, CONTINUECONSTRUCT, and EXIT CONSTRUCT statements, along with theget_fldbuf( ), fgl_lastkey( ), and field_touched( ) functions.

NEXT FIELD is an optional statement used to move the cursor to thespecified field-name, or to the NEXT or PREVIOUS field.

field-name is an unquoted screen field name.

NEXT is an optional keyword that indicates that the destination fieldfor NEXT FIELD is the immediately following field in field-list.

PREVIOUS is an optional keyword that indicates that the destination fieldfor NEXT FIELD is the immediately preceding field in field-list.

CONTINUECONSTRUCT

is an optional statement that returns program control to theCONSTRUCT statement and positions the cursor in the screenfield last occupied.

EXITCONSTRUCT

is an optional statement that terminates the CONSTRUCTstatement, without executing the AFTER CONSTRUCT clause,and generates the Boolean expression.

ENDCONSTRUCT

is a statement that indicates the end of the CONSTRUCTstatement. This statement is necessary only when you includea BEFORE CONSTRUCT, AFTER CONSTRUCT, BEFORE FIELD,AFTER FIELD, or ON KEY clause.

(3 of 3)


CONSTRUCT

General Usage4GL constructs a character variable by associating each column name in theON clause with the search condition that the user entered into the corre-sponding form field. You can use the information stored in the variable in theWHERE clause of a prepared SQL statement to specify a set of rows from thedatabase. Usually, you use this character variable as WHERE clause criteriafor a prepared SELECT statement.

To use the CONSTRUCT statement

1. Define screen fields in the form specification file.

2. Define the character variable using the DEFINE statement.

3. Open and display the screen form by using either of the following:

■ The OPEN FORM and DISPLAY FORM statements.

■ The OPEN WINDOW statement with the WITH FORM clausespecified.

4. Use the CONSTRUCT statement to create a character variablecontaining the Boolean expression based on the search criteria theuser entered in the fields.

The CONSTRUCT statement activates the current form. The current form isthe last form displayed, or, if you are using windows, the last form displayedin the current window.

When the CONSTRUCT statement completes, the form is cleared.

When 4GL encounters the CONSTRUCT statement, it does the following:

1. Clears all screen fields listed in the CONSTRUCT.

2. Executes the statements in the BEFORE CONSTRUCT clause, if theclause is specified.

3. Moves the cursor to the first screen field in the list.

4. Waits for the user to enter a search criteria in the field.

After you press the Accept key, CONSTRUCT executes the AFTERCONSTRUCT clause, if one is specified. It then creates a Boolean expressionthat specifies the search criteria and stores the Boolean expression in thecharacter variable. If no criteria were entered, the generic expression “ 1=1”is assigned to the character variable.


The BY NAME Keywords

You can use this character variable in a WHERE clause of an SQL statement tosearch the database for matching rows.

To search the database for matching rows

1. Concatenate the character variable containing the Booleanexpression with one or more character strings to create the stringversion of the statement to execute.

2. Use the PREPARE statement to create an executable SQL statementfrom the string generated in the previous step.

3. Execute the prepared statement in one of the following ways:

■ To execute a prepared SELECT statement (not a SELECT ... INTOstatement), use a cursor with the DECLARE and FOREACH (orOPEN and FETCH) statements.

■ To execute an SQL statement other than SELECT or to executea SELECT ... INTO statement, use the EXECUTE statement.

The BY NAME KeywordsYou can use the BY NAME keywords when the fields on the screen form havethe same names as the corresponding columns in the ON clause. (If you donot use the BY NAME option, you must list the fields in the FROM clause.) Theuser can position the cursor only in those fields that are implied in the BYNAME clause.

For example, the following CONSTRUCT statement assigns search criteria tothe character variable query_1. You can enter search criteria in fields namedcompany, address1, address2, city, state, and zipcode. Because these fieldshave the same names as the columns specified after the ON keyword, thestatement uses the BY NAME keywords, as follows:

CONSTRUCT BY NAME query_1 ONcompany, address1, address2, city, state, zipcode

A functionally equivalent CONSTRUCT statement is:

CONSTRUCT query_1 ONcompany, address1, address2, city, state, zipcodeFROMcompany, address1, address2, city, state, zipcode


The ON Clause

If the column names in a CONSTRUCT BY NAME statement are associatedwith field names in a screen array, the construct takes place in the first row ofthe screen array. If you want the CONSTRUCT to take place in a different rowof the screen array, you must use the FROM clause and cannot use the BYNAME keywords.

You cannot preface column names with an owner name when you use the BYNAME keywords; a compile-time error will result. Use the FROM clause tospecify table aliases in the field list when any column names contain anowner name. This is demonstrated in the section “The FROM Clause.”

The ON ClauseThe ON clause specifies a list of database columns for which the user willenter search criteria. These columns can be in different tables. If theCONSTRUCT statement includes the BY NAME clause, the fields on the screenform must have the same names as the columns listed after the ON keyword.If the CONSTRUCT statement includes a FROM clause, the list of columns inthe ON clause must correspond in order and in number to the list of fields inthe FROM clause.

You can use the notation tablename.* as a shorthand for all or part of a columnlist. The order of the columns in tablename depends on the order in whichcolumn names appear in the syscolumns system catalog at the time youcompile your program. (If you have used ALTER TABLE to change the orderor number of the columns in the table since you compiled your program, youwill probably need to modify and/or recompile your program and the formsthat depend on it.)

The following example uses the customer.* notation as a shorthand for a listof all columns in the customer table and cust.* as a shorthand for theelements in the cust screen record:

CONSTRUCT query_1 ON customer.* FROM cust.*


The FROM Clause

The FROM ClauseYou must use the FROM clause instead of the BY NAME clause under thefollowing conditions:

■ The fields on the screen have different names than the correspondingcolumns in the ON clause.

■ You want the CONSTRUCT to take place on a row other than the firstrow of the screen array.

■ You need to specify owner names for columns in the ON clause.

■ You want to specify an order for the screen fields other than thedefault order. (The order of the fields in the screen record determinesthe default order of the screen fields.)

You can position the cursor only in fields specified in the FROM clause. Thelist of fields in the FROM clause must correspond in order and in number tothe list of columns in the ON clause, as in the following example:

CONSTRUCT query_1 ONcompany, address1, address2, city, state, zipcodeFROM company, address1, address2, city, state, zipcode

When you use screen-record.* as a shorthand for all or part of a field list, besure that the order of the fields implied in the screen-record.* notation corre-sponds to the order of the columns in the ON clause. (The order of the fieldsin screen-record.* depends on its definition in the screen form.)

In the following CONSTRUCT statement, the field list includes the stock_numand manu_code fields, as well as the screen record s_stock.* that correspondsto the remaining columns in the stock table:

CONSTRUCT query_1 ON stock.* FROM stock_num, manu_code,s_stock.*

To use screen-array field names in the FROM clause, you must use thenotation screen-record [n].field-name to specify the row in which the constructtakes place. n must be greater than 0, and the CONSTRUCT takes place on thenth row. For example, the following CONSTRUCT statement allows you toenter search criteria in the third row of the screen array s_items:

CONSTRUCT query_1 ON items.* FROM s_items[3].*


The ATTRIBUTE Clause

You must use the FROM clause to specify table aliases in the field list whenany column names in the ON clause contain an owner name. In the followingCONSTRUCT statement, cust is the table alias created in the form specificationfor the actg.customer table. This table alias is prefixed to each field in theFROM clause because the columns in the ON clause include an owner name.

CONSTRUCT query_1 ONactg.customer.fname, actg.customer.lname,actg.customer.companyFROM cust.fname, cust.lname, cust.company

The ATTRIBUTE ClauseYou can use the ATTRIBUTE clause to apply display attributes to the fieldsspecified implicitly with the BY NAME keywords or explicitly in the FROMclause. Note that screen display attributes specified in the ATTRIBUTE clauseapply to all fields in the field list. The new attributes apply only during theCONSTRUCT statement. When the CONSTRUCT statement completes, theform reverts to its previous attributes.

Use of the ATTRIBUTES clause supersedes the following default attributes:

■ Default attributes listed in syscolatt. (For information on thesyscolatt utility, see Appendix B, “INFORMIX-4GL Utility Programs,”in the INFORMIX-4GL Reference Version 6.0.)

■ Default attributes in the form specification file.

The CONSTRUCT attributes temporarily override any display attributes in anOPTIONS or OPEN WINDOW statement for these fields.



The keywords in the following table can appear in the ATTRIBUTE clause.

The column labeled “Interpretation” indicates how an attribute appears on acolor terminal (for the first four keywords) or on a monochrome terminal (forthe remaining keywords). For example, on color terminals, NORMAL is inter-preted as WHITE, while BOLD is interpreted as RED.

If you specify the INVISIBLE attribute, 4GL does not display the data in thefield. However, the data is stored in the character variable that contains theselection criteria and is also available by using the get_fldbuf( ) function.

You must include at least one keyword in the ATTRIBUTE clause. You canspecify none or one of the keywords in the first keyword column and fromnone to three keywords from the second keyword column (however, someterminals might not support some combinations).

Keyword Interpretation Keyword

NORMAL white REVERSE

BOLD red BLINK

DIM blue UNDERLINE

INVISIBLE non-printing

WHITE normal

YELLOW bold

MAGENTA bold

RED bold

CYAN dim

GREEN dim

BLUE dim

BLACK dim


The HELP Clause

The following CONSTRUCT statement includes an ATTRIBUTE clause thatspecifies REVERSE for values entered in screen fields that have the samenames as the columns in the customer table:

CONSTRUCT BY NAME query_1 ON customer.*ATTRIBUTE (REVERSE)

These keywords can produce the effects indicated only when the termcap orterminfo files and the physical terminals support the attribute. For moreinformation on using these files, see Appendix I in the INFORMIX-4GLReference Version 6.0.

On UNIX systems that use terminfo files rather than termcap, 4GL does notsupport attributes that specify colors, and the only valid keywords areREVERSE and UNDERLINE.

Important: Some terminal entries in termcap or terminfo include the sg#1 orxmc#1 capabilities. If you are using one of these terminals and if the attributesspecified for the CONSTRUCT statement are different than the attributes of thecurrent form or window, 4GL replaces the right and left square brackets that indicatethe input fields with blank characters. 4GL uses the blank character as a transitioncharacter between the different attributes.

The HELP ClauseYou can use the HELP clause to provide optional help information for thestatement. 4GL displays this information when the user presses the Help key(CTRL-W by default).

The help-number identifies the message in the help file. The help file is acompiled help message file whose name you specify in the HELP FILE clauseof the OPTIONS statement. Use the mkmessage utility to create a compiledversion of the help file. For more information on using the mkmessage utility,see Appendix B “INFORMIX-4GL Utility Programs” in the INFORMIX-4GLReference Version 6.0.

To provide field-level help, use an ON KEY clause with the infield( ) function.The query1 demonstration program illustrates this approach.


The BEFORE CONSTRUCT Clause

The BEFORE CONSTRUCT Clause4GL clears all participating screen fields when it first executes a CONSTRUCTstatement. You can use the BEFORE CONSTRUCT clause to supply differentdefault field values.

4GL executes the statements in the BEFORE CONSTRUCT clause once beforeit allows you to perform the query by example. You can use DISPLAY state-ments in the BEFORE CONSTRUCT clause to populate the fields; DISPLAYinitializes the field buffers to the displayed values.

For example, the following CONSTRUCT statement displays the value HRO inthe manu_code field. If the user does not change the HRO value beforepressing the Accept key, the query by example selects rows with the valueHRO in the manu_code column:

CONSTRUCT query_1 ON stock.* FROM s_stock.*BEFORE CONSTRUCT

LET p_stock.manu_code = "HRO"DISPLAY p_stock.manu_code TO stock.manu_code

END CONSTRUCT

A CONSTRUCT statement can include only one BEFORE CONSTRUCT clause.

The AFTER CONSTRUCT Clause4GL executes the statements in the AFTER CONSTRUCT clause once after theuser presses the Accept key and before 4GL constructs the string containingthe Boolean expression.

You can use the AFTER CONSTRUCT clause to validate, save, or alter thevalues of the screen field buffers. The section “Using Functions in aCONSTRUCT Statement” describes 4GL functions that commonly appear inthe AFTER CONSTRUCT clause.

You can place the CONTINUE CONSTRUCT statement or the NEXT FIELDstatement in this clause to return the cursor to the form. If you place aCONTINUE CONSTRUCT or NEXT FIELD statement within the AFTERCONSTRUCT clause, be sure it appears within a conditional statement.Otherwise, the user cannot exit the CONSTRUCT statement.


The BEFORE FIELD Clause

In the following program segment, a CONTINUE CONSTRUCT statementappears in an IF statement. You can exit the CONSTRUCT when selectioncriteria is entered for at least one field.

AFTER CONSTRUCTIF NOT field_touched(orders.*) THEN

MESSAGE "You must indicate at least one ","selection criteria."

CONTINUE CONSTRUCTEND IF

4GL executes the AFTER CONSTRUCT clause when you press one of thefollowing keys:

■ The Accept key

■ The Interrupt key (and the DEFER INTERRUPT statement hasexecuted)

■ The Quit key (and the DEFER QUIT statement has executed)

The AFTER CONSTRUCT clause is not executed in the following situations:

■ You press the Interrupt or Quit key and the DEFER INTERRUPT orDEFER QUIT statement, respectively, has not been executed. In eithercase, the program terminates immediately.

■ The EXIT CONSTRUCT statement terminates the CONSTRUCTstatement.

A CONSTRUCT statement can include only one AFTER CONSTRUCT clause.

The BEFORE FIELD Clause4GL executes the BEFORE FIELD clause associated with a field whenever thecursor enters the field and before the user types selection criteria. You canspecify only one BEFORE FIELD clause for each field.

You can use a NEXT FIELD statement within a BEFORE FIELD clause to restrictaccess to a field. You also can use a DISPLAY statement within a BEFOREFIELD clause to display a default value in a field.

The following example demonstrates using the BEFORE FIELD clause todisplay a message when the cursor enters the a field:

BEFORE FIELD stateMESSAGE "Press F2 or CTRL-B to display a list of states"


The AFTER FIELD Clause

The AFTER FIELD Clause4GL executes the AFTER FIELD clause associated with a field whenever thecursor leaves the field. The cursor can leave the field by one of the followingkeys:

■ Any arrow key

■ RETURN key

■ Accept key

■ TAB key

When the NEXT FIELD statement appears in an AFTER FIELD clause, 4GLplaces the cursor in the specified field. 4GL executes the AFTER FIELD clauseeven if the Accept key is the only key entered while the cursor is in the field.You can specify only one AFTER FIELD clause for each field.

For example, the following AFTER FIELD clause displays a message after thecursor leaves the state field, prompting you to enter search criteria:

AFTER FIELD stateMESSAGE "Press ESC to begin search"

The ON KEY Clause4GL executes the statements in the ON KEY clause whenever you presses oneof the keys specified in key-list. You can include the following keys in key-list.Type the key names in uppercase or lowercase.

ACCEPT INTERRUPT

DELETE LEFT

DOWN NEXTPAGE

ESC PREVPAGE

ESCAPE RIGHT

HELP TAB

INSERT UP

F1 through F64 CTRL-char(except A, D, H, K, L, R, or X)


The ON KEY Clause

The following table lists keys that require special consideration before youassign them in an ON KEY clause.

You might not be able to use other keys that have special meaning toyour version of the operating system. For example, you cannot use CTRL-Z onmany BSD UNIX systems. Also, CTRL-C, CTRL-S, and CTRL-Q have specialmeanings in many UNIX systems.

The following example demonstrates using the ON KEY clause to call a helpmessage. The BEFORE CONSTRUCT clause informs you how to access help:

BEFORE CONSTRUCTDISPLAY "Press F1 or CTRL-W for help"

ON KEY (f1, control-w)CALL customer_help()

Key Special Considerations

ESC or ESCAPE You must specify another key as the Accept key becauseESCAPE is the default Accept key. Reassign the Accept keyvia the OPTIONS statement.

F3 You must specify another key as the Next key because F3 is thedefault Next key. Reassign the Next key via the OPTIONSstatement.

F4 You must specify another key as the Previous key because F4 isthe default Previous key. Reassign the Previous key via theOPTIONS statement.

INTERRUPT You must execute a DEFER INTERRUPT statement. (When youpress the Interrupt key under these conditions, 4GL executes thestatements in the ON KEY clause and sets int_flag to nonzero, butdoes not terminate the CONSTRUCT statement.)

CTRL-charWhere char isA, D, H, I, J, L,M, R, X

4GL reserves these keys for field editing.

The regular meaning of CTRL-I (TAB), CTRL-J (LINEFEED) andCTRL-M (RETURN) is lost to you. Instead, the key is “trapped” by4GL and used to trigger the commands in the ON KEY clause. Forexample, if CTRL-M appears in an ON KEY clause, you cannotpress RETURN to advance the cursor to the next field. If you mustinclude one of these keys in an ON KEY clause, be careful torestrict the scope of the clause to specific fields


The NEXT FIELD Statement

If you trigger an ON KEY clause while entering data in the field, 4GL does thefollowing:

1. Suspends the input of the current field

2. Preserves the input buffer that contains the characters you havetyped

3. Executes the statements in the corresponding ON KEY clause

4. Restores the input buffer for the current screen field

5. Resumes input in the same field with the cursor repositioned whereit was when the ON KEY keystroke was pressed

You can change this default behavior by performing the following tasks inthe ON KEY clause:

■ Resuming input in another field by using the NEXT FIELD statement

■ Changing the input buffer value for the current field by assigninga new value to the corresponding variable and then displaying thevalue using DISPLAY TO or DISPLAY BY NAME

The NEXT FIELD StatementWhen you perform a query, 4GL moves the cursor from screen field to screenfield in the order specified in the FROM clause of the CONSTRUCT statement(or in the order implied by the column list in the ON clause of theCONSTRUCT BY NAME statement). However, you can use the NEXT FIELDstatement to explicitly position the cursor.

The NEXT FIELD statement has the following syntax:

NEXT FIELD { field-name | NEXT | PREVIOUS }

The NEXT keyword moves the cursor to the next field as specified in theCONSTRUCT statement; the PREVIOUS keyword moves the cursor to theprevious field as specified in the CONSTRUCT statement. The NEXT FIELDfield-name statement moves the cursor to field-name.

A NEXT FIELD statement can appear in a BEFORE CONSTRUCT clause (forexample, to position the cursor at a different starting field) and in a BEFOREFIELD clause (for example, to restrict access to a field). However, it is morecommonly used in the AFTER FIELD, ON KEY, and AFTER CONSTRUCTclauses.



The following AFTER FIELD clause includes a NEXT FIELD statement. 4GLexecutes the AFTER FIELD clause when you move the cursor out of thezipcode field. The field_touched( ) function checks whether you haveentered a value into the field. If field_touched( ) returns TRUE, thenget_fldbuf( ) retrieves the value entered into the field during a query andassigns it to the p_zipcode program variable. If the first character in thep_zipcode variable is not a 9, the program displays an error, clears thezipcode field, and returns the cursor to the field.

AFTER FIELD zipcodeIF field_touched(zipcode) THEN

LET p_zipcode = get_fldbuf(zipcode)IF p_zipcode[1,1] <> "9" THEN

ERROR "You can only search area 9."CLEAR zipcodeNEXT FIELD zipcode

END IFEND IF

4GL immediately positions the cursor in the form when it encountersthe NEXT FIELD statement; any statements that physically follow the NEXTFIELD statement in a clause are not executed. This is demonstrated in thefollowing program segment. 4GL never sees the qty_help( ) function, since itis positioned after the NEXT FIELD statement in the ON KEY clause:

ON KEY (CONTROL-B, F4)IF infield(stock_num) OR infield(manufact) THEN

CALL stock_help()NEXT FIELD quantityCALL qty_help() -- this function is never called

END IF

In most situations, the NEXT FIELD should appear in a conditional statement.The NEXT FIELD statement must appear in a conditional statement when itappears in an AFTER CONSTRUCT clause; otherwise, you cannot exit thequery.


The CONTINUE CONSTRUCT Statement

The CONTINUE CONSTRUCT StatementThe CONTINUE CONSTRUCT statement skips all subsequent statements thatmight appear in the current clause of the CONSTRUCT statement and returnsthe cursor in the screen form at the last screen field occupied.

The CONTINUE CONSTRUCT statement is useful in situations where programcontrol is nested within multiple conditional statements and you want toreturn control to the user. It also is useful in an AFTER CONSTRUCT clause,where you can examine field buffers and, depending on their contents, returnthe cursor to the form.

For example, the following program segment appears in the query1 programincluded in the demonstration application.

An IF statement tests whether the user has entered a value into any formfield. If no field has been touched, the program prompts the user to indicatewhether to retrieve all customer records. If the user types N or n, theCONTINUE CONSTRUCT statement is triggered and the cursor is repositionedin the form. The user is given another opportunity to enter selection criteria.If the user types a key other than N or n, the program terminates the IFstatement and reaches the END CONSTRUCT statement.

CONSTRUCT BY NAME query1 on customer.*...AFTER CONSTRUCT

IF NOT field_touched(customer.*) THENPROMPT "Do you really want to see ",

"all customer rows? (y/n)"FOR CHAR answer

IF answer MATCHES "[Nn]" THENCONTINUE CONSTRUCT

END IFEND IF

END CONSTRUCT

When a test contained in an AFTER CONSTRUCT clause identifies a field thatrequires the user’s attention, you should use the NEXT FIELD statement,rather than CONTINUE CONSTRUCT, to position the cursor explicitly in thefield.


The EXIT CONSTRUCT Statement

The EXIT CONSTRUCT StatementThe EXIT CONSTRUCT statement causes 4GL to do the following:

■ Skip all statements between the EXIT CONSTRUCT statement and theEND CONSTRUCT statement and deactivate the form

■ Create the character variable containing the Boolean expression

■ Resume execution at the first statement following the ENDCONSTRUCT statement

4GL does not execute the AFTER CONSTRUCT clause, if one is present.

The END CONSTRUCT StatementThe END CONSTRUCT statement indicates the end of the CONSTRUCTstatement. This statement should follow the last BEFORE CONSTRUCT, AFTERCONSTRUCT, BEFORE FIELD, AFTER FIELD, or ON KEY clause. If you do notinclude any of these clauses, you do not need to include the END CONSTRUCTstatement.

AUTONEXT Ignored by CONSTRUCTDuring a CONSTRUCT statement, when you enter criteria into a field and youare using the AUTONEXT attribute, if you key past the form field delimiter,the cursor does not enter the next field. This is because the CONSTRUCTstatement ignores the AUTONEXT attribute so that you can query for largeranges, alternatives, and so forth.

Using WORDWRAP in CONSTRUCTIn Version 4.11 and earlier, when CONSTRUCT was working on a multi-segment field with the WORDWRAP attribute set, the initial input wasdisplayed in the first segment of the field. When the input no longer fit in thefirst segment, it overflowed into the second and subsequent segments of thefield. However, it also cleared the overflow line at the bottom of the screen,even though no data appeared there.


Using WORDWRAP in CONSTRUCT

In Version 4.12 and later, multi-segment fields behave in the same way assingle-segment fields; when the first segment is full, the overflow linedisplays the extra data. The CONSTRUCT statement uses only the firstsegment and the overflow line of a WORDWRAP field; it does not use the extrasegments. This should provide sufficient space for query input.

Any form field with the WORDWRAP attribute can span several lines. If thesegments of a multi-segment wordwrapped field are not aligned in a singlecolumn, then moving backwards from a later segment can cause the cursorto skip some segments entirely, or leave the cursor in odd places inside thesegment. (For explanations on segments and WORDWRAP fields, see theINFORMIX-4GL Reference Version 6.0.)

You should avoid overly complex placement of word-wrapped fields, suchas:

[f001 ][f001 ] [f001 ]

However, the following type of form field configurations producepredictable results:

[f001 ]

Specifying Search CriteriaThe CONSTRUCT statement lets you specify search criteria by filling in thefields of the screen form with the search data. This process is called a queryby example. To find all the rows, the user presses the Accept key (ESC bydefault), without filling in any fields on the screen form. You can use thesymbols to search for values less than, equal to, greater than, or within arange. The following table summarizes the use of search criteria.

Symbol NameDataTypes Pattern

= equal to all =x, =

> greater than all >x

< less than all <x

>= greater than or equal to all >=x

(1 of 2)



You cannot use these search symbols with BYTE and TEXT data. If you specifya search criteria that exceeds the length of a field, 4GL opens a work space onthe Comment line. This erases any comments present.

The following list explains the symbols in the table above.

<= less than or equal to all <=x

<> not equal to all <>x

: range all x:y

.. range DATETIME,INTERVAL

x..y

* wildcard for any string CHAR *x, x*, *x*

? single-character wildcard CHAR ?x, x?, ?x?, x??

| or all a|b...

[ ] list of values (see below) CHAR [xy]*, [xy]?

Symbol Explanation

x The x means any value of the appropriate data type for the search field.Enter the value immediately after any one of the first six query symbolsin the preceding table. Do not leave a space between a query symboland the value.

=x The equal sign (=) is the default query symbol for non-charactercolumns, and for character columns in which the user enters a searchvalue that does not contain wildcards. If you enter a character valuethat does not contain a wildcard character, the CONSTRUCT statementproduces the following relational statement:char-column = “value”

= The equal sign (=) with no value searches for a database row thatcontains a NULL column. Enter = * to find a row that contains a columnwith only an asterisk.

>, <, >=, These symbols imply an ordering of the data in the column.

(1 of 2)

Symbol NameDataTypes Pattern

(2 of 2)



<=, <> For character data, “greater than” means later in the ASCII collatingsequence (where a > A > 1), as listed in Appendix G of theINFORMIX-4GL Reference. For DATE and DATETIME data, “greaterthan” means after. For INTERVAL data, “greater than” means a longerspan of time.

: The colon in x: y searches for all values between the x and y value,inclusive. The y value must be larger than the x value. The searchcriterion 1: 10 would find all rows with a value in that column from 1through 10.

.. Substitute two periods (..) for the colon in DATETIME and INTERVALranges to avoid ambiguity with the field separator in hh:mm:ss values.

* The asterisk (*) is the string wildcard, representing zero or morecharacters. Use the asterisk character as follows:

The search value *ts* in the field corresponding to the lname column ofthe customer table finds two names, Watson and Albertson.

The search value S* in the same field finds Sadler and Sipes.

The search value *er finds the four names Sadler, Miller, Jaeger, andBaxter.

? The question mark (?) is the single-character wildcard. The user can usethe question mark to find values matching a pattern in which thenumber of characters is fixed, as follows:

Enter Eriks?n to search for names like “Erikson” and “Eriksen.”

Enter New??n to search for names like “Newton,” “Newman,” and“Newson,” but not “Newilsson.”

| The symbol | between values a and b means the logical OR. In the fieldcorresponding to the column customer_num, the following entryretrieves any of three numbers:

102|105|118

[ ] When used in conjunction with the * and ? wildcard characters, thebrackets enclose a list of characters, including ranges, to match. A caret(^) as the first character within the brackets matches any character notlisted. The search value [^AB]* specifies all strings beginning withcharacters other than A or B. The search value [^d-f]* specifies allstrings beginning with characters other than lowercase d, e, or f.

If you omit the * or ? wildcard, 4GL treats the brackets as literalcharacters, not as match operators.

(2 of 2)



Searching for All RowsIf you enter no values in the fields, 4GL constructs the following Booleanexpression:

" 1=1"

When used in a WHERE clause, this search condition causes 4GL to select allthe rows. You can place a conditional statement after the CONSTRUCTstatement to check for this expression. You might want to check for thisexpression to prevent users from selecting all rows.

For example, the following program segment checks for the 1=1 expression.If this expression is found, the IF statement limits the resulting rows by speci-fying an expression that looks for customers with numbers less than or equalto 110:

CONSTRUCT BY NAME query_1 ON customer.*AFTER CONSTRUCT

IF query_1 = " 1=1" THENLET query_1 = " customer_num <= 110"

END IF

Note that the string “ 1=1” begins with a blank character. A good place to trapthe “ 1=1” expression is the AFTER CONSTRUCT clause.



Positioning the CursorWhen the user presses TAB or RETURN, 4GL moves the cursor from one screenfield to the next in the order specified in the FROM clause of the CONSTRUCTstatement (or in the order implied by the column list in the ON clause of theCONSTRUCT BY NAME statement). However, the user can press the keysshown in the following table to alter this behavior and to explicitly positionthe cursor.

When moving the cursor to a new field, the CONSTRUCT statement clears theComment line and the Error line. The Comment line displays the text definedwith the COMMENTS attribute in the form specification file. The Error linedisplays system error messages and ERROR statement messages.

Key Purpose

[↓] By default, moves the cursor to the next field. If you specify the FIELD ORDERUNCONSTRAINED option of the OPTIONS statement, this key moves thecursor to the field below the current field.

[↑] By default, moves the cursor to the previous field. If you specify the FIELDORDER UNCONSTRAINED option of the OPTIONS statement, this key movesthe cursor to the field above the current field.

[→] Moves the cursor one space to the right inside a screen field, without erasingthe current character. If the cursor reaches the end of the field, 4GL places thecursor in a large field at the bottom of the screen allowing the user to continueentering a query by example value.

[←] Moves the cursor one space to the left inside a screen field, without erasingthe current character. If the cursor reaches the beginning of the field, 4GLplaces the cursor at the beginning of the previous field.


Using Functions in a CONSTRUCT Statement

Editing During a QueryThe keys in the following table are available for editing while performinga query.

Using Functions in a CONSTRUCT Statement4GL provides a variety of functions to use in the CONSTRUCT statement.4GL functions are described in Chapter 4 of the INFORMIX-4GL ReferenceVersion 6.0.

Key Purpose

CTRL-A toggles between insert and typeover mode.

CTRL-D deletes characters from the current cursorposition to the end of the field.

CTRL-H moves the cursor nondestructively one spaceto the left. It is equivalent to pressing [←].

CTRL-L moves the cursor nondestructively one spaceto the right. It is equivalent to pressing [→].

CTRL-R redisplays the screen.

CTRL-X deletes the character beneath the cursor.


Using Functions in a CONSTRUCT Statement

The functions in the following table allow you to access field buffers andkeystroke buffers.

Each field in a form has only one field buffer, and a buffer cannot be used bytwo different statements simultaneously. If a CONSTRUCT statement calls afunction that includes an INPUT, INPUT ARRAY, or CONSTRUCT statement,and both statements use the same form, you can overwrite one or more of thefield buffers. When you use fields in a CONSTRUCT statement, you shouldnot reuse them in an INPUT, INPUT ARRAY, or another CONSTRUCTstatement until the first CONSTRUCT statement finishes.

If you plan to display the same form more than one time and will access theform fields, you should open a new window and open and display a secondcopy of the form. 4GL allocates a separate set of buffers to each form, and youcan be certain that your program is retrieving the correct field values.

Function Description

field_touched( ) Returns TRUE when the user has “touched” (made a change to)a screen field passed as an argument to the function. Moving thecursor through a field (by using the RETURN, TAB, or arrow keys)does not mark a field as touched. This function also does notregister the effect of statements that appear in the BEFORECONSTRUCT clause. For example, you can assign values to fieldsin the BEFORE CONSTRUCT clause without having the fieldsmarked as touched.

get_fldbuf( ) Returns the character values of the contents of one or more fieldsin the currently active form.

fgl_lastkey( ) Returns an integer value corresponding to the most recentkeystroke executed by the user while in the screen form.

infield( ) Returns TRUE if the field passed as an argument to the functionis the name of the current field.


Interrupts in a CONSTRUCT Statement

Interrupts in a CONSTRUCT StatementVersion 4.12 of 4GL and 4GL/RDS introduced a change in the output ofCONSTRUCT statements interrupted by the user striking the Interrupt key(usually CTRL-C or DEL) or the Quit key (usually CTRL-\). This applies only toprograms that have executed DEFER INTERRUPT and DEFER QUIT; otherwise,an Interrupt or Quit keystroke terminates the application immediately.

In 4.10 and prior releases, using an Interrupt or Quit keystroke in aCONSTRUCT statement produced an output query string that contained thecontents of the field buffer at the time the Interrupt keystroke was pressed.Therefore, if the program did not carefully check the value of int_flag beforeproceeding, it could miss the fact that the CONSTRUCT had been interruptedand proceed with a bad query.

In Version 4.12 and later, a CONSTRUCT statement interrupted by anInterrupt or Quit keystroke produces a NULL query string. This minimizesthe chance that an unchecked interrupt condition will proceed undetected. ACONSTRUCT statement can only produce a NULL query string if it was inter-rupted; thus you can detect an interrupt or quit without having to check bothint_flag and quit_flag. (A successful CONSTRUCT statement for which youentered no criteria before striking the Accept key produces the string “ 1=1”,not a null string.)

Strings Produced by a CONSTRUCT StatementIn Version 4.11 and prior releases, 4GL would put double quote (“) charactersaround the field values entered during the CONSTRUCT statement regardlessof the data types. The resulting WHERE clause for the SQL statement mightnot be compatible with non-Informix database engines because of the doublequotes.

In Release 4.12 and later, the CONSTRUCT statement puts single quotes (‘)around the following data types:

CHAR, DATE, DATETIME, INTERVAL, VARCHAR

The following data types are not enclosed in quotes:

FLOAT, SMALLFLOAT, DECIMAL, MONEY, INTEGER, SMALLINT, SERIAL


Behavior of CONSTRUCT and get_fldbuf()

These changes allow 4GL programs to work with INFORMIX-GateWayand talk to DB2/400, DB2/MVS (aka DB2) and DB2/VM (aka SQL/DS). Thesechanges are known colloquially as the DRDA changes. The latest versionsof the INFORMIX-GateWay product automatically convert the keywordMATCHES to LIKE, and generates an error if the MATCHES string containsa character class enclosed in square brackets (for example, [a-z]).

Behavior of CONSTRUCT and get_fldbuf()In 4GL Version 6.00 and earlier, the behavior of get_fldbuf() during INPUTand CONSTRUCT statements was as shown in the following table.

Versions 6.01 and higher behaves in a subtly different way duringa CONSTRUCT statement.

During a CONSTRUCT statement, the current version of get_fldbuf() returnsa string based on the appearance of the field (this string will be used toconstruct the query); CONSTRUCT no longer checks to see if the field has beentouched.

Statement Behavior of get_fldbuf()

INPUT It returned a blank string if the field looked empty.

CONSTRUCT It returned a null string if the field was untouched;it returned a blank string if the field was touched.

Statement Behavior of get_fldbuf()

INPUT Returns a blank string if the field looks empty.

CONSTRUCT Returns a null string if the field looks empty.



Completing a QueryThe following conditions can terminate the CONSTRUCT statement:

■ The user presses one of the following keys:

❑ The Accept key

❑ The RETURN or TAB key from the last field (and INPUT WRAPis not set via the OPTIONS statement)

❑ The Interrupt key

❑ The Quit key

■ 4GL executes the EXIT CONSTRUCT statement.

The user must press the Accept key to explicitly complete the query underthe following conditions:

■ INPUT WRAP is specified via the OPTIONS statement.

■ An AFTER FIELD clause for the last form field includes a NEXT FIELDstatement.

By default, the Accept, Interrupt, or Quit key terminates the query and exitsthe CONSTRUCT statement. An Interrupt or Quit also terminates the programimmediately unless DEFER INTERRUPT or DEFER QUIT, respectively, has beenexecuted.

If 4GL previously executed a DEFER INTERRUPT statement in the program,an Interrupt causes 4GL to do the following:

■ Set the global variable int_flag to a nonzero value

■ Terminate CONSTRUCT statement processing (except the AFTERCONSTRUCT block, if any) but not the 4GL program

If 4GL previously executed a DEFER QUIT statement in the program, a Quitsignal causes 4GL to do the following:

■ Set the global variable quit_flag to a nonzero value

■ Terminate CONSTRUCT statement processing (except the AFTERCONSTRUCT block, if any) but not the 4GL program



When the user terminates a CONSTRUCT, 4GL executes the statements in theAFTER CONSTRUCT clause. (If the CONSTRUCT is terminated by an EXITCONSTRUCT statement, 4GL does not execute the statements in the AFTERCONSTRUCT clause.) 4GL does not execute the statements in the AFTER FIELDclause of the current field in these cases.

When a NEXT FIELD statement appears in either of these clauses, 4GL ignoresthe Accept keystroke and instead moves the cursor to the specified field.

ExamplesThe following program segment uses a simple CONSTRUCT statement tospecify the search condition of a WHERE clause. The variable query_1 isdefined as CHAR(250), and the cursor_1 cursor executes the query.

CONSTRUCT BY NAME query_1ON order_num, customer_num, order_date, ship_dateATTRIBUTE(BOLD)

LET s1 = "SELECT * FROM orders WHERE ", query_1 CLIPPED," ORDER BY order_date, order_num"

PREPARE s_1 FROM s1DECLARE cursor_1 CURSOR FOR s_1FOREACH cursor_1 INTO order_rec.*

...END FOREACH

The following program segment appears in the query1 program included inthe demonstration application:

CONSTRUCT BY NAME query_1 ON customer.*

BEFORE CONSTRUCTMESSAGE "Enter search criteria; ",

"press ESC to begin search."DISPLAY "Press F1 or CTRL-W for field help." AT 2,1

ON KEY (F1, CONTROL-W)CALL customer_help() -- display field level help

BEFORE FIELD stateMESSAGE "Press F2 or CTRL-B ",

"to display a list of states."

ON KEY (F2, CONTROL-B)IF infield(state) THEN

CALL statehelp() -- display list of statesEND IF



AFTER FIELD stateMESSAGE "Enter search criteria; ",

"press ESC to begin search."

AFTER CONSTRUCT -- check for blank search criteriaIF NOT field_touched(customer.*) THEN

PROMPT "Do you really want to see ","all customer rows? (y/n) "FOR CHAR answer

IF answer MATCHES "[Nn]" THENMESSAGE "Enter search criteria; ",

"press ESC to begin search."CONTINUE CONSTRUCT

-- reenter query by exampleEND IF

END IFEND CONSTRUCT

LET s1 = "SELECT * FROM customer WHERE ",query_1 CLIPPED

PREPARE s_1 FROM s1DECLARE q_curs CURSOR FOR s_1DISPLAY "" AT 2,1 -- clear line 2 of textLET exist = 0...

Related StatementsOPEN FORM, OPTIONS, SELECT


FOREACH

FOREACHUse the FOREACH statement to cause a sequence of statements to beexecuted for each row returned from a query.

Syntax

FOREACH cursor-name [ USING variable-list ][ INTO variable-list ]

statement...[ CONTINUE FOREACH]...[ EXIT FOREACH]...

END FOREACH

FOREACH is a required keyword.

cursor-name is the name of a cursor that previously was DECLAREd.

USING is an optional keyword.

variable-list is a list of one or more program variables, separated bycommas.

INTO is an optional keyword.

variable-list is a list of one or more program variables, separated bycommas.

CONTINUEFOREACH

is an optional statement.

EXITFOREACH

is an optional statement.

ENDFOREACH

are required keywords.


FOREACH

Notes1. The FOREACH statement repeats the sequence of statements up to

END FOREACH for each row returned by the query associated withcursor-name. The FOREACH statement opens the cursor andperforms successive fetches until the active list of the cursor isexhausted.

2. The USING clause is required if, and only if, the cursor expectsuser-supplied search values to replace '?' placeholders. As withOPEN, the number and data types of placeholders in the preparedSELECT statement must correspond exactly to the number and datatypes of the values given in the USING variable list. FOREACHperforms an implied OPEN statement.

3. If both the USING clause and the INTO clause are used, the USINGclause must precede the INTO clause.

4. The INTO clause is required only if there is no INTO clause in theSELECT statement associated with cursor-name, and vice versa. It liststhe variables into which 4GL places the values returned by the query.

5. When fetching into a program array, you must place the INTO clauseon the FOREACH statement and not on the SELECT-statement of aDECLARE statement.

6. The CONTINUE FOREACH statement interrupts the sequence andcauses program control to return to the top of the sequence and toFETCH the next row of the query.

7. The EXIT FOREACH statement interrupts the sequence and causesprogram control to jump to the first statement following the ENDFOREACH keywords.

8. If the query returns no rows, none of the statements up the ENDFOREACH is executed, and program control passes immediately tothe first statement following END FOREACH. If you need to knowwhether any rows were returned, you can set up a flag or a counteras in the example that follows these notes.


FOREACH

9. If your database has transactions and the cursor was declared byDECLARE FOR UPDATE but not DECLARE WITH HOLD, theFOREACH statement must be executed within a transaction. (You canopen an update cursor that was declared with a DECLARE WITHHOLD via a FOREACH statement outside a transaction, but youcannot roll back any changes that the cursor performs outside thetransaction. In this situation, each UPDATE WHERE CURRENT OF isautomatically committed as a singleton transaction.)

10. Each FOREACH statement internally generates an OPEN statement, aFETCH loop (which normally exits when NOTFOUND is returned),and a CLOSE statement. If a FETCH returns an error other thanNOTFOUND (error 100, the normal end-of-data indication) and theprogram has executed a WHENEVER ERROR GOTO statement, theimplicit CLOSE statement is not executed. (Also, if you useWHENEVER ERROR CALL and the called function terminates theprogram, the cursor is not closed before entering the called function.)If you use WHENEVER ERROR GOTO to resume execution at someother area of the program, the cursor might remain open and wouldneed to be manually closed.

11. Because the internally generated CLOSE statement can change thevalues in the SQLCA structure, the value of SQLCA.SQLERRD[3] afterthe END FOREACH does not represent the number of rows fetched bythe FOREACH. If you need to know the number of rows fetched bythe FOREACH, you must maintain your own row counter.


FOREACH

ExamplePROMPT "Enter cut-off date for query: "

FOR o_date

DECLARE q_curs CURSOR FORSELECT order_num, o.customer_num, company

FROM orders o, customer cWHERE o.customer_num = c.customer_num

AND order_date < o_date

LET counter = 0

FOREACH q_curs INTO ord_num, cust_num, compLET counter = counter + 1CALL scan (ord_num, cust_num, comp)

END FOREACH

IF counter = 0ERROR "No orders before ", o_date

END IF

Related StatementsCONTINUE, EXIT, FETCH, FOR, OPEN, WHILE, WHENEVER


GLOBALS

GLOBALSUse the GLOBALS statement to define one or more variables to be globalvariables or to refer to the file where global variables are defined.

Syntax

GLOBALS {“filename”}DEFINE-statement...

END GLOBALS

Notes1. Multiple GLOBALS statements are allowed in a module. However,

you can define any particular global variable in, at most, oneGLOBALS statement. In other words, do not include any variablename in a GLOBALS definition that has already been used in anotherGLOBALS definition, even if both references have the same data typeand size. If you repeat a variable name in this manner, the compilermight give an error message noting the doubly defined variables.

2. The GLOBALS filename statement must occur earlier in every file thanany function that makes reference to a global variable.

3. The GLOBALS statement must lie outside the MAIN program blockand any FUNCTION or REPORT routines.

GLOBALS is a required keyword.

filename is the pathname of the file where the global variables aredefined.

DEFINE-statement

is a DEFINE statement for the global variable.

ENDGLOBALS

are required keywords that terminate the GLOBALS statementwhen variables are defined.


Variables in Global Scope

4. If any global variable is DEFINEd LIKE a database column, theDATABASE statement naming the database must precede theGLOBALS statement.

5. The description of GLOBALS defines two forms of the GLOBALSstatement: one defines variables while the other refers to the filewhere global variables are defined. The first note clearly states “youcan define any particular global variable in, at most, one GLOBALSstatement.” This is because the 4GL compiler converts 4GL variablesinto native C data types (for simple types) or into structures (formore complex types).

ExamplesExample 1: GLOBALS with variable definitions

DATABASE storesGLOBALS

DEFINE p_customer RECORD LIKE customer.*...

END GLOBALS

Example 2: GLOBALS with file reference

GLOBALS "d4_globals.4gl"DEFINE module_variable CHAR(20)...

FUNCTION myfunc()DEFINE function_variable CHAR(5)...

END FUNCTION

Related StatementDEFINE

Variables in Global ScopeCurrently 4GL does not check for the name conflicts between global variablesand system function calls. To avoid errors at runtime, do not use systemfunction names such as read( ), open( ), or stat( ), as names for the globalvariables.


INPUT

INPUTUse the INPUT statement to let a user enter values for one or more fields ofa screen form. The INPUT statement assigns the values entered in the fields toprogram variables.

Syntax

INPUT{

BY NAME variable-list [WITHOUT DEFAULTS]|variable-list [WITHOUT DEFAULTS]

FROM {field-list | screen-record [[n]].*} [, ...]}[ATTRIBUTE (attribute-list)][HELP help-number][

{{

BEFORE INPUT|AFTER INPUT|BEFORE FIELD field-list|AFTER FIELD field-list|ON KEY (key-list)

}{

statement|NEXT FIELD { field-name | NEXT | PREVIOUS }|CONTINUE INPUT|EXIT INPUT

} ...} ...END INPUT

]


INPUT

INPUT is a required keyword.

BY NAME are optional keywords used to instruct 4GL to match the namesof variables to screen field names.

variable-list is a list of program variables to display.

WITHOUTDEFAULTS

are optional keywords used to display the current values invariable-list on the screen.

FROM is a required keyword used to specify the screen fields whosevalues will be assigned to variable-list.


screen-record is the identifier of a collection of field names defined in a formspecification as a screen record.

[ n ] is an integer or integer variable, enclosed in brackets, speci-fying the row in a screen array in which the INPUT takes place.

ATTRIBUTE is an optional keyword used to specify screen input attributes.

attribute-list is a list (in parentheses) of one or more screen input attributes,separated by commas.

HELP is an optional keyword used to indicate the help message forthe statement.

help-number is an integer that identifies the help message for the INPUTstatement. You must have used the OPTIONS statement previ-ously to identify the help file containing the message.

BEFOREINPUT

is an optional clause containing one or more 4GL statements.4GL executes these statements before allowing the user toinput any values.

AFTER INPUT is an optional clause containing one or more 4GL statements.4GL executes these statements after the user types the Acceptkey, unless the user terminates the INPUT statement with theInterrupt or Quit key (or a runtime error occurs).

(1 of 3)


INPUT

BEFOREFIELD

is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user moves thecursor into one of the specified fields and before the user entersa value in the field.

AFTER FIELD is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user moves thecursor out of one of the specified fields.

ON KEY is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user types one ofthe keys specified in key-list.

4GL preserves a field’s contents and the cursor location withinthe field and resumes the INPUT after running the ON KEYstatements.


■ F1 through F64

■ CTRL-char, where char is a letter.

■ UP, DOWN, LEFT, RIGHT, NEXTPAGE, PREVPAGE, INSERT,DELETE, ACCEPT, ESCAPE, ESC, INTERRUPT, HELP, or TAB.

For specific limitations on key-list, see “The ON KEY Clause”on page 6-57.

statement is any 4GL statement. This can include NEXT FIELD, CONTINUEINPUT, and EXIT INPUT statements, along with theget_fldbuf( ), fgl_lastkey( ), and field_touched( ) functions.



NEXT is an optional keyword used to move the cursor to the nextfield. The order of the fields is determined by the FROM clauseof the INPUT statement.

(2 of 3)


INPUT

General Usage

To use the INPUT statement

1. Define screen fields in the form specification file.

2. Define program variables using the DEFINE statement.

3. Open and display the screen form with either of the following:

■ The OPEN FORM and DISPLAY FORM statements

■ The OPEN WINDOW statement with its WITH FORM clause

4. Use the INPUT statement to assign values to the program variablesfrom data the user entered in the screen fields.

After the user presses the Accept key, you can use the INSERT statement toinsert the program variables values into the appropriate database tables.

PREVIOUS is an optional keyword used to move the cursor to theprevious field. The order of the fields is determined by theFROM clause of the INPUT statement.

CONTINUEINPUT

is an optional statement that returns program control to theINPUT statement and positions the cursor in the screen fieldlast occupied.

EXIT INPUT is an optional statement that directs 4GL to terminate theINPUT statement.

END INPUT is a statement that terminates the INPUT statement. Thisstatement is necessary only when you include a BEFOREINPUT, AFTER INPUT, BEFORE FIELD, AFTER FIELD, or ON KEYclause.

(3 of 3)


The BY NAME Clause

When 4GL encounters the INPUT statement, 4GL does the following:

1. Displays any default values in the screen fields (unless the WITHOUTDEFAULTS clause is specified)

2. Moves the cursor to the first screen field

3. Waits for the user to enter a value in a field

4. Assigns the screen field value to the corresponding program variablewhen the user leaves the field (by using the RETURN key or an arrowkey)

The INPUT statement activates the current form. The current form is the lastform displayed, or, if you have opened a window, the last form displayed inthe current window. 4GL stacks the windows in the order of creation. You canrearrange the stack by using the CURRENT WINDOW statement.

When the INPUT statement completes, the form deactivates.

The BY NAME ClauseUse the BY NAME clause when the program variables have the same namesas the fields on the screen. The BY NAME clause binds the form fields tovariables implicitly. The user can only input in the screen fields implied in theBY NAME clause. To use this clause, you must first define program variableswith the same names as the screen fields from which you want to acceptinput. 4GL ignores the record name prefix when matching the names. Thebasic variable and field names must be unique and unambiguous.

The user can only input values for those fields on the screen implied in the BYNAME clause. For example, the following INPUT statement defines variablesfor all the screen fields except customer_num:

DEFINE p_customer RECORD LIKE customer.*...INPUT BY NAME p_customer.fname, p_customer.lname,

p_customer.company, p_customer.address1,p_customer.address2, p_customer.city, p_customer.state,p_customer.zipcode, p_customer.phone

Because the customer_num variable does not appear in the list of variables,the user cannot enter a value for that field.


The WITHOUT DEFAULTS Clause

A functionally equivalent INPUT statement is:

DEFINE p_customer RECORD LIKE customer.*...INPUT BY NAME p_customer.fname THRU p_customer.phone

The WITHOUT DEFAULTS ClauseUse the WITHOUT DEFAULTS clause to display the current values of variableson the screen when the INPUT statement begins. If you omit the WITHOUTDEFAULTS clause, 4GL displays the default values of the variables in thefields.

To use the WITHOUT DEFAULTS clause

1. Initialize the variables with the values you want to display.

2. Use the INPUT statement with the WITHOUT DEFAULTS clause todisplay the current variable values and to allow the user to changethe variables.

For example, the following INPUT statement causes 4GL to display the value“Send via air express” in the ship_instruct field:

LET p_orders.ship_instruct = "Send via air express"

INPUT BY NAME p_orders.order_date THRU p_orders.paid_dateWITHOUT DEFAULTS

END INPUT

The WITHOUT DEFAULTS clause is useful when you want to allow the userto make changes to existing rows of the database. You can display the existingvalues on the screen before the user begins changing data. Thefield_touched( ) function can help you determine which fields have beenaltered and therefore require database updates.

If you omit the WITHOUT DEFAULTS clause, 4GL checks the followinglocations for the default field values:

1. The DEFAULT attribute from the form specification

2. The DEFAULT column value as stored in the syscolval system table

4GL assigns NULL values to all variables for which no default is set.


The FROM Clause

The FROM ClauseWhen program variables do not have the same names as the screen fields, usethe FROM clause. You must supply the same number of variables and fieldsand list them in the same order on either side of the FROM clause.

The user can position the cursor only in fields specified in the FROM clause.The list of fields must correspond in order and in number to the list ofvariables, as in the following example:

DEFINE p_customer RECORD LIKE customer.*

INPUT p_customer.fname, p_customer.lnameFROM fname, lname

You can use the THRU keyword to implicitly select all variables between twospecified variables. For example, the following statement maps fields to allvariables between fname and phone:

INPUT p_customer.fname THRU p_customer.phoneFROM fname, lname, company, address1,

address2, city, state, zipcode, phone

If you define a screen record as fname THRU lname in the form specificationfile, you can abbreviate this statement even further as follows:

INPUT p_customer.fname THRU p_customer.phoneFROM sc_cust.*

The ATTRIBUTE ClauseUse the ATTRIBUTE clause to specify screen input attributes.

If you specify the form’s attributes with the INPUT statement, the newattributes apply only during the current activation of the form. When theuser deactivates the form, the form reverts to its previous attributes.

The following INPUT statement assigns the REVERSE attribute to the INPUTstatement:

INPUT p_addr.* FROM sc_addr.*ATTRIBUTE (REVERSE)



Use of the ATTRIBUTE clause supersedes the following default attributes:

■ Default attributes listed in syscolatt

■ Default attributes in the form specification file

The INPUT attributes temporarily override any display attributes specified ina DISPLAY FORM, OPTIONS, or OPEN WINDOW statement for these fields.

The keywords in the following table can appear in the ATTRIBUTE clause.

The column labeled “Interpretation” indicates how an attribute appears ona color terminal (for the first four keywords) or on a monochrome terminal(for the remaining keywords). For example, on color terminals NORMAL isinterpreted as WHITE, while BOLD is interpreted as RED.




BOLD red BLINK

DIM blue UNDERLINE


WHITE normal

YELLOW bold

MAGENTA bold

RED bold

CYAN dim

GREEN dim

BLUE dim

BLACK dim


The HELP Clause

These keywords can produce the effects indicated only when the termcap orterminfo files and the physical terminals support the attribute. (For moreinformation on these files, see Appendix F “Modifying termcap and terminfo”in the INFORMIX-4GL Reference Version 6.0.)


Important: Some terminal entries in termcap or terminfo include the sg#1 orxmc#1 capabilities. If you are using one of these terminals and if the attributesspecified for the INPUT statement are different than the attributes of the current formor window, 4GL replaces the right and left square brackets that indicate the inputfields with blank characters. 4GL uses the blank character as a transition characterbetween the different attributes.

The HELP ClauseThe HELP clause specifies the number of the help message to display for theINPUT statement. 4GL displays the help message when the user presses theHelp key from any field listed in the INPUT statement. The Help key isCTRL-W by default.

The help-number identifies the message in the help file. The help file is acompiled message file whose name you specify in the HELP FILE clause of theOPTIONS statement. Use the mkmessage utility to create a compiled versionof the help file. For more information on using the mkmessage utility, seeAppendix B “INFORMIX-4GL Utility Programs” in the INFORMIX-4GLReference Version 6.0.

The following example tells 4GL to display message 12 when a user pressesthe Help key:

INPUT p_customer.fname, p_customer.lnameFROM fname, lname HELP 12

To provide field-level help, use an ON KEY clause with the infield( ) andshow_help( ) functions.


The BEFORE INPUT Clause

The BEFORE INPUT Clause4GL executes the BEFORE INPUT clause after displaying the default values inthe fields and before letting the user enter any values. (If you specified theWITHOUT DEFAULTS clause, 4GL displays the existing values of thevariables, not the default values, before executing the BEFORE INPUT clause.)

You can use the BEFORE INPUT clause to display messages on how to use theINPUT statement. For example, the following INPUT statement displays amessage informing the user how to enter data into the table:

INPUT BY NAME p_customer.*BEFORE INPUT

DISPLAY "Press ESC to enter data" AT 1,1...

END INPUT

An INPUT statement can include only one BEFORE INPUT clause.

The AFTER INPUT Clause4GL executes the AFTER INPUT clause when the user presses the Accept key.You can use the AFTER INPUT clause to validate the values the user enteredby using the get_fldbuf( ) or field_touched( ) functions within the AFTERINPUT clause.

You can place the NEXT FIELD statement in this clause to return the cursor tothe form. If you place a NEXT FIELD statement within the AFTER INPUTclause, be sure it appears within a conditional statement. Otherwise, the usercannot exit the INPUT statement and leave the form.

The following example demonstrates using the AFTER INPUT clause torequire that a first name be specified for customers with the last name Smith:

INPUT BY NAME p_customer.fname THRU p_customer.phoneAFTER INPUT

IF p_customer.lname="Smith" THENIF NOT field_touched(p_customer.fname) THEN

CALL mess("You must enter a first name.")NEXT FIELD fname

END IFEND IF

END INPUT


The BEFORE FIELD Clause

4GL only executes the AFTER INPUT clause when the INPUT statementterminates with the user pressing one of the following:

■ The Accept key



4GL does not execute the AFTER INPUT clause in the following situations:

■ The user presses the Interrupt or Quit key and the DEFER INTERRUPTor DEFER QUIT statement, respectively, has not executed. In eithercase, the program terminates immediately.

■ The EXIT INPUT statement terminates the INPUT ARRAY statement.

An INPUT statement can include only one AFTER INPUT clause.

The BEFORE FIELD Clause4GL executes the BEFORE FIELD clause associated with a field whenever thecursor enters the field and before the user enters a value. You can specify onlyone BEFORE FIELD clause for each field.

The following program segment defines two BEFORE FIELD clauses. Whenthe cursor enters the fname or lname field, 4GL displays a message:

BEFORE FIELD fnameMESSAGE "Enter first name of customer"

BEFORE FIELD lnameMESSAGE "Enter last name of customer"

...

You can use a NEXT FIELD statement within a BEFORE FIELD clause to restrictaccess to a field. You can also use a DISPLAY statement within a BEFOREFIELD clause to display a default value in a field.



The AFTER FIELD Clause4GL executes the AFTER FIELD clause associated with a field when the cursorleaves the field. The cursor can leave the field by one of the following keys:

■ Any arrow key

■ TAB key

■ RETURN key

■ Accept key

When the NEXT FIELD statement appears in an AFTER FIELD clause, 4GLplaces the cursor in the specified field. If an AFTER FIELD clause appears foreach form field, and a NEXT FIELD statement appears in each clause, the useris unable to leave the form. You can specify only one AFTER FIELD clause foreach field.

The following INPUT statement displays a message when the cursor leavesthe phone field:

AFTER FIELD phoneMESSAGE "Are you sure this number is correct?"

The ON KEY Clause4GL executes the statements in the ON KEY clause whenever the user pressesone of the keys specified in key-list. You can include the following keyconstants in key-list. Type the key names in uppercase or lowercase.

ACCEPT INTERRUPT

DELETE LEFT

DOWN NEXTPAGE

ESC PREVPAGE

ESCAPE RIGHT

HELP TAB

INSERT UP

F1 through F64 CTRL-char (except A, D, H, K, L, R, or X)


The ON KEY Clause

The following table lists keys that require special consideration before youuse them in an ON KEY clause.

You might not be able to use other keys that have special meaning toyour version of the operating system. For example, you cannot use CTRL-Z onmany BSD UNIX systems. Also, CTRL-C, CTRL-S, and CTRL- Q have specialmeanings in many UNIX systems.

The following example demonstrates using the ON KEY clause to call a helpmessage. The BEFORE INPUT clause informs the user how to access help:

BEFORE INPUTDISPLAY "Press F1 or CTRL-W for help"

ON KEY (F1, CONTROL-F)CALL customer_help()

If the user triggers an ON KEY clause while entering data in the field,4GL does the following:


2. Preserves the input buffer that contains the characters the user hastyped


Key Special Considerations

ESC orESCAPE

You must specify another key as the Accept key because ESCAPEis the default Accept key. Reassign the Accept key in the OPTIONSstatement.

INTERRUPT You must have executed the DEFER INTERRUPT statement. (Whenthe user presses the Interrupt key under these conditions, 4GLexecutes the statements in the ON KEY clause and sets int_flag tononzero, but does not terminate the INPUT statement.)

CTRL-char

Where char isA, D, H, I, J,K, L, M, R, X


The regular meaning of CTRL-I (TAB), CTRL-J (LINEFEED) andCTRL-M (RETURN) is lost to the user. Instead, the key is “trapped”by 4GL and used to trigger the commands in the ON KEY clause.For example, if CTRL-M appears in an ON KEY clause, the usercannot press RETURN to advance the cursor to the next field. If youmust include one of these keys in an ON KEY clause, be careful torestrict the scope of the clause to specific fields.



4. If NEXT FIELD was not executed by the ON KEY clause, restores theinput buffer for the current screen field

5. If NEXT FIELD was not executed by the ON KEY clause, resumes inputin the same field with the cursor returned to its position at the timethe ON KEY keystroke occurred

You can change this default behavior by resuming input in another field byusing the NEXT FIELD statement.

You can also use this clause to provide accelerator keys for common functionssuch as saving and deleting.

You can use the infield( ) function to make field-specific responses in theaction for an ON KEY clause.

The NEXT FIELD StatementThe NEXT FIELD statement has the following syntax:


The NEXT keyword moves the cursor to the next field as specified in theINPUT statement; the PREVIOUS keyword moves the cursor to the previousfield as specified in the INPUT statement. The NEXT FIELD field-namestatement moves the cursor to field-name.

By default, 4GL moves the cursor among the screen fields according to theorder in which you specified the fields in the INPUT variable clause. The usercontrols the movement from field to field by using the arrow keys, TAB, andRETURN. However, you can explicitly position the cursor by using the NEXTFIELD statement.

For example, to wrap from the last field of a form to the first field of a form,use the NEXT FIELD statement after an AFTER FIELD clause for the last field ofthe form. You can also use the INPUT WRAP option of the OPTIONS statementfor the same effect.

While a NEXT FIELD statement can appear in a BEFORE FIELD clause (forexample, to restrict access to a field), it is more commonly used in the AFTERFIELD, ON KEY, or AFTER INPUT clauses.


The CONTINUE INPUT Statement

The following example demonstrates using the NEXT FIELD statement in anON KEY clause. 4GL executes the ON KEY clause when the user presses F1. Ifthe cursor is in the city field, 4GL displays San Francisco in the city field andCA in the state field, and then moves the cursor to the zipcode field.

ON KEY (F1)IF infield(city) THEN

LET p_addr.city = "San Francisco"DISPLAY p_addr.city TO cityLET p_addr.state = "CA"DISPLAY p_addr.state TO stateNEXT FIELD zipcode

END IF

4GL immediately positions the cursor in the form when it encounters theNEXT FIELD statement; it does not execute any statements that follow theNEXT FIELD statement in the clause. Therefore, any unconditional NEXTFIELD statements should be the last statement in the clause.

For example, 4GL never sees the qty_help( ) function in the followingprogram segment:

ON KEY (CONTROL-B, F4)IF infield(stock_num) OR infield(manufact) THEN

CALL stock_help()NEXT FIELD quantityCALL qty_help() -- function is never called

END IF

In most situations, the NEXT FIELD should appear in a conditional statement.The NEXT FIELD statement must appear in a conditional statement when itappears in an AFTER INPUT or AFTER ROW clause; otherwise, the user cannotexit the form.

The CONTINUE INPUT StatementThe CONTINUE INPUT statement skips all subsequent statements that mightappear in the current clause of the INPUT statement and returns the cursor inthe screen form at the last screen field occupied.

The CONTINUE INPUT statement is useful in situations where programcontrol is nested within multiple conditional statements and you want toreturn control to the user. It is also useful in an AFTER INPUT clause, whereyou can examine field buffers and, depending on their contents, return thecursor to the form.


The EXIT INPUT Statement

The EXIT INPUT StatementThe EXIT INPUT statement causes 4GL to do the following:

■ Skip all the statements between the EXIT INPUT and the END INPUTstatements

■ Deactivate the form

■ Resume execution at the first statement following the END INPUTstatement

If you specified an AFTER INPUT clause, 4GL does not execute the clause.

The END INPUT StatementThe END INPUT statement indicates the end of the INPUT statement. Thisstatement should follow the last BEFORE INPUT, AFTER INPUT, BEFOREFIELD, AFTER FIELD, or ON KEY clause. If you do not include any of theseclauses, you do not need to include the END INPUT statement.

WORDWRAP in INPUTThis is a change to default behavior.

In Release 4.10.UC1, form fields with the WORDWRAP attribute and formfields with the WORDWRAP COMPRESS attribute behaved in a similar fashionto each other. Also, the routine to perform compression was not consistentwith the specification.

To preserve backward compatibility, Version 4.12 changed the defaultbehavior of WORDWRAP fields that had no keyword following WORDWRAP;these now behave like WORDWRAP COMPRESS. If the attributes for a fieldreads either WORDWRAP COMPRESS or just WORDWRAP, compress mode isactive. To render the compress mode inactive, use the new attributeWORDWRAP NONCOMPRESS. This behavior persists in 6.0 releases of 4GL.

Now, the WORDWRAP input routines behave as specified in the documen-tation. All user-typed blanks remain in both COMPRESS and NONCOMPRESSmode. In COMPRESS mode, only line-padding (editor) blanks are eliminated.


AFTER INPUT Control Block

AFTER INPUT Control BlockThe INPUT statement supports an optional AFTER INPUT control block andallow the developer to inspect, validate, save, or alter the values of the formfield buffers.

The NEXT FIELD statement in the AFTER INPUT control block gives the 4GLdeveloper the ability to prevent the user from completing the INPUTstatement if some programmer- defined semantic criteria are not satisfied.For example, if values in the various fields are in conflict, the developer coulddetour the user back to the conflicting fields before allowing the INPUTstatement to complete, by having conditional NEXT FIELD statements in theAFTER INPUT block. For example:

INPUT p_items.* from s_items.*...AFTER ROW

IF p_items.manu_code = "PNG" THENMESSAGE "REMINDER: PNG products are currently on

import hold"NEXT FIELD manu_code

END IF...

END INPUT

The NEXT FIELD statement in the AFTER INPUT control block, if executed,now keeps the user entry in the INPUT statement, with the cursor in themanu_code field, regardless of what navigation key you use to leave theINPUT statement (for example, ACCEPT).

Using Functions in an INPUT Statement4GL provides a variety of functions to use in the INPUT statement.4GL functions are described in Chapter 4 of the INFORMIX-4GL ReferenceVersion 6.0. (The field_touched( ), get_fldbuf( ), and fgl_lastkey( ) functionsare described in the section “New Functions” in this supplement.)


Using Functions in an INPUT Statement

The following functions allow you to access field buffers and keystrokebuffers.

Each field in a form has only one field buffer, and a buffer cannot be used bytwo different statements simultaneously.

If you plan to display the same form more than one time and will access theform fields, you should open a new window and open and display a secondcopy of the form. 4GL allocates a separate set of buffers to each form, and youcan be certain that your program is retrieving the correct field values.

For information on verifying that your terminal definition allows 4GL torecognize functions, see Appendix I of the INFORMIX-4GL Reference Version6.0.


field_touched( ) Returns TRUE when the user has “touched” (made a change to)a screen field passed as an argument to the function. Moving thecursor through a field (by using the RETURN, TAB, or arrowkeys) does not mark a field as touched. This function also doesnot register the effect of statements that appear in the BEFOREINPUT clause. For example, you can assign values to fields in theBEFORE INPUT clause without having the fields marked astouched.

get_fldbuf( ) Returns the character values of the contents of one or more fieldsin the currently active form.

fgl_lastkey( ) Returns an INTEGER value corresponding to the most recentkeystroke executed by the user while in the screen form.



Using Functions in an INPUT Statement

Positioning the CursorWhen the user presses TAB or RETURN, 4GL moves the cursor from one screenfield to the next in the default order. 4GL determines the default order basedon the following:

■ If you specify the BY NAME clause, 4GL uses the order implied by theprogram variables specified in the BY NAME clause.

■ Otherwise, 4GL uses order of the screen fields specified on the FROMclause of the INPUT statement.

However, the user can select the following keys to explicitly position thecursor.

Key Purpose

[↓] By default, moves the cursor to the next field. If you specify the FIELDORDER UNCONSTRAINED option of the OPTIONS statement, this keymoves the cursor to the field below the current field. If no field is belowthe current field and a field exists to the left of the current field, 4GLmoves the cursor to the field to the left.

[↑] By default, moves the cursor to the previous field. If you specify the FIELDORDER UNCONSTRAINED option of the OPTIONS statement, this keymoves the cursor to the field above the current field. If no field is abovethe current field and a field exists to the left of the current field, 4GLmoves the cursor to the field to the left.

[→] Moves the cursor one space to the right inside a screen field, withouterasing the current character. At the end of the screen field, 4GL moves thecursor to the first character position of the next screen field. The [→] keyis equivalent to the CTRL-L editing command.

[←] Moves the cursor one space to the left inside a screen field without erasingthe current character. At the beginning of the screen field, 4GL moves thecursor to the first character position of the previous field. The [←] key isequivalent to the CTRL-H editing command.


Editing During an INPUT Statement

Editing During an INPUT StatementThe following keys allow users to edit the information they enter intoa screen form.

Completing an INPUT StatementThe following conditions can terminate the INPUT statement:


❑ The Accept key

❑ The RETURN or TAB key from the last field (an INPUT WRAP is notset in an OPTIONS statement)


❑ The Quit key

■ 4GL executes the EXIT INPUT statement.

All of these conditions deactivate the form.

Key Purpose

CTRL-A Toggles between insert and typeover mode.

CTRL-D Deletes characters from the current cursorposition to the end of the field.

CTRL-H Moves the cursor nondestructively one spaceto the left. It is equivalent to pressing [←].

CTRL-L Moves the cursor nondestructively one spaceto the right. It is equivalent to pressing [→].

CTRL-R Redisplays the screen.

CTRL-X Deletes the character beneath the cursor.


Completing an INPUT Statement

The user must press the Accept key to explicitly complete the INPUTstatement under the following conditions:

■ INPUT WRAP is specified in the OPTIONS statement.

■ An AFTER FIELD clause for the last form field includes a NEXT FIELDstatement.

By default, both the Accept key and the Interrupt key complete the INPUTstatement. However, an Interrupt or Quit, by default, also terminates theprogram immediately. DEFER INTERRUPT and DEFER QUIT, respectively,allow the 4GL program to absorb those signals and continue.



■ Terminate the INPUT statement but not the 4GL program



■ Terminate the INPUT statement but not the 4GL program

When INPUT terminates, 4GL executes the following clauses:

1. The AFTER FIELD clause of the current field

2. The AFTER INPUT clause

However, if INPUT terminates by an EXIT INPUT statement, 4GL does notexecute either of these clauses. If a NEXT FIELD statement appears in either ofthese clauses, 4GL ignores the Accept keystroke and moves the cursor to thespecified field.


Completing an INPUT Statement

ExamplesIn the following INPUT statement, the BEFORE FIELD clause displaysmessages for the user. The AFTER INPUT clause checks if the value the userentered in the field is allowed. If the user presses the CTRL-B key while thecursor is in the city field, the ON KEY clause:

1. displays the value San Francisco in the city field.

2. displays CA in the state field.

3. places the cursor in the zipcode field.INPUT p_customer.fname THRU p_customer.phone

FROM sc_cust.*ATTRIBUTE(REVERSE)

BEFORE FIELD cityMESSAGE "Press CTRL-B to select default city, San

Francisco"

ON KEY (CONTROL-B)IF infield(city) THEN

LET p_customer.city = "San Francisco"DISPLAY p_customer.city TO cityLET p_customer.state = "CA"DISPLAY p_customer.state TO stateNEXT FIELD zipcode

END IF

END INPUT

Related StatementsDEFINE, DISPLAY, DISPLAY FORM, GLOBALS, INITIALIZE, INPUT ARRAY,OPTIONS


INPUT ARRAY

INPUT ARRAYUse the INPUT ARRAY statement to let a user enter data in a screen array.4GL then stores the data entered into a program record array.

Syntax

INPUT ARRAY record-array[WITHOUT DEFAULTS] FROM screen-array.*[HELP help-number][ATTRIBUTE (attribute-list)][

{{

BEFORE {INPUT | ROW | INSERT |DELETE}|AFTER {INPUT | ROW | INSERT |DELETE}|BEFORE FIELD field-list|AFTER FIELD field-list|ON KEY (key-list)

}{

statement|NEXT FIELD {field-name | NEXT |PREVIOUS}|CONTINUE INPUT|EXIT INPUT

} ...} ...END INPUT

]


INPUT ARRAY

INPUT ARRAYare required keywords.

record-array is a program array name. Usually, record-array is an array ofrecords.

The number of variables in a row of record-array must be thesame as the number of fields in a row of screen-array. The sizeof record-array can be bigger than the size of screen-array. In thiscase, the user will need to scroll through the rows.

WITHOUTDEFAULTS

are optional keywords to display the current values ofrecord-array.

FROM is a required keyword to specify the screen-array whose valuewill be assigned to record-array.

screen-array is the name of a screen record that corresponds to the fields ina row of a screen array.

HELP is an optional keyword used to indicate a help message.

help-number is an integer that identifies the help message for this INPUTARRAY statement. You must have used the OPTIONS statementpreviously to identify the help file containing the message.

ATTRIBUTE is an optional keyword used to specify screen input attributes.

attribute-list is a list (in parentheses) of screen attributes.

BEFORE is an optional keyword that, along with the INPUT, ROW,INSERT, or DELETE keyword, constitutes a clause. The clausecan contain one or more 4GL statements.

INPUT is an optional keyword that, along with the BEFORE or AFTERkeyword, constitutes a clause.

If BEFORE INPUT is specified, 4GL executes the group ofstatements before allowing the user to input any values.

If AFTER INPUT is specified, 4GL executes the group ofstatements after the user types the Accept key, unless the userterminates the INPUT ARRAY statement with the Interrupt orQuit key (or a runtime error occurs).

(1 of 4)


INPUT ARRAY

ROW is an optional keyword that, along with the BEFORE or AFTERkeyword, constitutes a clause.

If BEFORE ROW is specified, 4GL executes the group ofstatements when the cursor moves into a new form row.

If AFTER ROW is specified, 4GL executes the group ofstatements when the cursor leaves a row as well as when theuser presses the Accept key.

INSERT is an optional keyword that, along with the BEFORE or AFTERkeyword, constitutes a clause.

If BEFORE INSERT is specified, 4GL executes the group ofstatements before the user inserts a row in the screen array.

If AFTER INSERT is specified, 4GL executes the group ofstatements after the user inserts a row into the screen array.

DELETE is an optional keyword that, along with the BEFORE or AFTERkeyword, constitutes a clause.

If BEFORE DELETE is specified, 4GL executes the group ofstatements when the user presses the Delete key to deletea row of the screen array.

If AFTER DELETE is specified, 4GL executes the group ofstatements after 4GL deletes a row.

AFTER is an optional keyword that, along with the INPUT, ROW,INSERT, or DELETE keyword, constitutes a clause. The clausecan contain one or more 4GL statements.

BEFOREFIELD

is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user moves thecursor into one of the specified fields and before the user entersa value in the field.


AFTER FIELD is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user moves thecursor out of one of the specified fields.

(2 of 4)


INPUT ARRAY

ON KEY is an optional clause containing one or more 4GL statements.4GL executes these statements each time the user types one ofthe keys specified in key-list.

4GL preserves a field’s contents and the cursor location withinthe field and resumes the INPUT ARRAY after running the ONKEY statements.


■ F1 through F64

■ CTRL-char, where char is a letter.


DELETE, ACCEPT, ESCAPE, ESC, INTERRUPT, HELP, or TAB.

■ For specific limitations on key-list, see the section titled“The ON KEY Clause” on page 6-82.

statement is any 4GL statement. This can include NEXT FIELD, CONTINUEINPUT, and EXIT INPUT statements, along with theget_fldbuf( ), fgl_lastkey( ), and field_touched( ) functions.



NEXT is an optional keyword used to move the cursor to the nextfield. The order of the fields is determined by the FROM clauseof the INPUT ARRAY statement.

PREVIOUS is an optional keyword used to move the cursor to theprevious field. The order of the fields is determined by theFROM clause of the INPUT ARRAY statement.

CONTINUEINPUT

is an optional statement that returns program control to theINPUT ARRAY statement and positions the cursor in the screenfield last occupied.

(3 of 4)


INPUT ARRAY

General Usage

To use the INPUT ARRAY statement

1. Define a screen record array in the form specification file.

2. Define a program record array by using the DEFINE statement.

The record members should correspond in name and order to thescreen record elements.

3. Open and display the screen by using either of the following:

■ The OPEN FORM and DISPLAY FORM statements

■ The OPEN WINDOW statement with its WITH FORM clause

4. Use the INPUT ARRAY statement to assign values to the programarray from data the user entered in the screen array.

After the user presses the Accept key, you can insert the values in theprogram record array into the appropriate database tables by using theINSERT statement.

When 4GL encounters the INPUT ARRAY statement, 4GL does the following:

1. Displays default values (if any) in the screen field

2. Moves the cursor to the first screen field in the first row

3. Waits for the user to enter a value in the field

4. Assigns the screen field value to the corresponding program arrayrow when the user leaves the field

EXIT INPUT is an optional statement that directs 4GL to terminate theINPUT ARRAY statement.

END INPUT is a statement that terminates the INPUT ARRAY statement.This statement is necessary only when you include a BEFORE,AFTER, or ON KEY clause.

(4 of 4)


The WITHOUT DEFAULTS Clause

The INPUT ARRAY statement activates the current form. The current formis the last form displayed, or, if you have opened a window, the last formdisplayed in the current window. 4GL stacks the windows in order ofcreation. You can rearrange the stack by using the CURRENT WINDOWstatement.

When the INPUT ARRAY statement terminates, the form deactivates.

The WITHOUT DEFAULTS ClauseUse the WITHOUT DEFAULTS clause to display the current values of theprogram record array in the screen array. If you omit the WITHOUTDEFAULTS clause, 4GL displays the default values in the fields.

To use the WITHOUT DEFAULTS clause

1. Initialize the program array with the values you want to display.

2. Call the set_count( ) function to tell 4GL how many rows arecurrently stored in the program array.

3. Use the INPUT ARRAY statement with the WITHOUT DEFAULTSclause to display the current values in the program array and toallow the user to add, change, or delete these rows.

The WITHOUT DEFAULTS clause is useful when you want to allow the userto make changes to existing rows of the database. You can display the existingvalues on the screen before the user begins changing data. Thefield_touched( ) function can help you determine which fields have beenaltered and therefore require database updates.

If you omit the WITHOUT DEFAULTS clause, 4GL determines the defaultvalues by looking in the following places, in the order indicated:

1. The DEFAULT attribute from the form specification

2. The DEFAULT column as stored in the syscolval table

4GL assigns NULL values for all variables for which no default is set.


The FROM Clause

The FROM ClauseThe FROM clause binds the screen array fields to the program array variables.This binding allows you to manipulate within the program the values theuser enters on the form. The number and order of variables in a row of therecord array must match the fields in a row of the screen array. Each variablemust have the same or compatible data type as the corresponding screenfield.

The HELP ClauseThe HELP clause specifies the number of the help message to display for theINPUT ARRAY statement. 4GL displays the help message when the userpresses the Help key from any array field. The Help key is CTRL-W by default.

The help-number identifies the message in the help file. The help file isa compiled ASCII file whose name you specify in the HELP FILE clause of theOPTIONS statement. Use the mkmessage utility to create a compiled versionof the help file. For more information on using the mkmessage utility, seeAppendix B “INFORMIX-4GL Utility Programs” in the INFORMIX-4GLReference Version 6.0.

The following example demonstrates specifying the help message numbered311 for the INPUT ARRAY statement:

INPUT ARRAY p_items FROM s_items.*HELP 311

To provide field-level help, use an ON KEY clause with the infield( ) andshow_help( ) functions.

The ATTRIBUTE ClauseUse the ATTRIBUTE clause to specify screen input attributes.

If you specify the form’s attributes with the INPUT ARRAY statement, the newattributes apply only during the current activation of the form. When theuser deactivates the form, the form reverts to its previous attributes. TheINPUT ARRAY attributes temporarily override any attributes specified in anOPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these fields.



Use the of ATTRIBUTE clause supersedes the following default attributes:

■ Default attributes listed in syscolatt

■ Default attributes in the form specification file

The following statement assigns the REVERSE attribute to the INPUT ARRAYstatement:

INPUT ARRAY p_items FROM s_items.* ATTRIBUTE (REVERSE)

The following keywords can appear in the ATTRIBUTE clause.

The column labeled “Interpretation” indicates how an attribute appears on acolor terminal (for the first four keywords) or on a monochrome terminal (forthe remaining keywords). For example, on color terminals NORMAL is inter-preted as WHITE, while BOLD is interpreted as RED.



BOLD red BLINK

DIM blue UNDERLINE


WHITE normal

YELLOW bold

MAGENTA bold

RED bold

CYAN dim

GREEN dim

BLUE dim

BLACK dim


The BEFORE INPUT Clause


These keywords can produce the effects indicated only when the termcap orterminfo files and the physical terminals support the attribute. For moreinformation on these files, see Appendix F “Modifying termcap and terminfo”in the INFORMIX-4GL Reference Version 6.0.


Important: Some terminal entries in termcap or terminfo include the sg#1 orxmc#1 capabilities. If you are using one of these terminals and if the attributesspecified for the INPUT ARRAY statement are different than the attributes of thecurrent form or window, 4GL replaces the right and left square brackets that indicatethe input fields with blank characters. 4GL uses the blank character as a transitioncharacter between the different attributes.

The BEFORE INPUT Clause4GL executes the BEFORE INPUT clause after displaying the default values inthe fields (unless you include the WITHOUT DEFAULTS clause) and beforeletting the user enter any values.

To populate the fields using DISPLAY statements in the BEFORE INPUT clause

1. Before the INPUT ARRAY statement, call set_count(1) to initialize thearray with one row.

2. Include the WITHOUT DEFAULTS clause in the INPUT ARRAYstatement.

3. Within the BEFORE INPUT clause, use one or more LET statements toassign values to the variables.

4. Use a DISPLAY statement to display the variable to the screen.


The BEFORE ROW Clause

The following example displays the value 2 in the stock_num field:

CALL set_count(1)INPUT ARRAY p_items WITHOUT DEFAULTS FROM s_items

BEFORE INPUTLET pa_curr = arr_curr()LET s_curr = scr_line()LET p_items[pa_curr].stock_num = 2DISPLAY p_items[pa_curr].stock_num TO

s_items[s_curr].stock_numNEXT FIELD manu_code

END INPUT

An INPUT ARRAY statement can include only one BEFORE INPUT clause.

The BEFORE ROW Clause4GL executes the BEFORE ROW clause in the following cases:

■ The cursor moves into a new form row.

■ An INSERT command fails due to lack of space.

■ An INSERT command is aborted by an Interrupt key.

■ The user presses the DELETE key.

You can specify only one BEFORE ROW clause.

The BEFORE INSERT Clause4GL executes the BEFORE INSERT clause in the following cases:

■ When the user begins entering rows into the array

■ After the user presses the Insert key to insert a new row in the middleof a screen array and before the row is added to the array

■ When the user moves the cursor to a blank row at the end of a screenarray

4GL executes the statements before the user enters information for eachsuccessive row.


The BEFORE DELETE Clause

The following BEFORE INSERT clause calls the get_item_num function beforeinserting a row into the screen array:

BEFORE INSERTCALL get_item_num()

The BEFORE DELETE Clause4GL executes the BEFORE DELETE clause after the user presses the DELETE keyand before 4GL actually deletes a row.

The AFTER INPUT Clause4GL executes the AFTER INPUT clause when the INPUT ARRAY statementterminates. An INPUT ARRAY statement can include only one AFTER INPUTclause.

You can use the AFTER INPUT clause to validate, save, or alter the values ofthe screen field buffers. For a description of 4GL functions that commonlyappear in the AFTER INPUT clause, see “Using Functions in an INPUTARRAY Statement” on page 6-88.

You can place the NEXT FIELD statement in this clause to return the cursor tothe form. If you place a NEXT FIELD statement within the AFTER INPUTclause, be sure it appears within a conditional statement. Otherwise, the usercannot exit the INPUT ARRAY statement and leave the form.

4GL only executes the AFTER INPUT clause when the INPUT ARRAY statementterminates with the user pressing one of the following:

■ The Accept key



4GL does not execute the AFTER INPUT clause in the following situations:

■ The user presses the Interrupt or Quit key and the DEFER INTERRUPTor DEFER QUIT statement, respectively, has not been executed. Ineither case, the program terminates immediately.

■ The EXIT INPUT statement terminates the INPUT ARRAY statement.


The AFTER ROW Clause

The AFTER ROW Clause4GL executes the AFTER ROW clause in the following cases:

■ When the user moves the cursor out of the current row by using oneof the following keys:

❑ Any arrow key

❑ RETURN key

❑ TAB key

❑ Accept key

■ When a row is inserted

You can specify only one AFTER ROW clause per INPUT ARRAY statement.If you specify both an AFTER ROW and AFTER INSERT clause, 4GL executesthe AFTER INPUT clause immediately after executing the AFTER ROW clause.

The following AFTER ROW clause calls the order_total function after thecursor leaves a row and the row is inserted:

AFTER ROWCALL order_total()

The AFTER INSERT Clause4GL executes the AFTER INSERT clause after the user inserts a row into thescreen array. A user inserts a row by doing the following:

■ Entering information in all the required fields of the current row

■ Moving the cursor out of the last input field by using one of thefollowing keys:

❑ any arrow key

❑ RETURN key

❑ TAB key

❑ Accept key

The following AFTER INSERT clause calls the renum_items( ) function afterinserting a row into the screen array:

AFTER INSERTCALL renum_items()


The AFTER DELETE Clause

The AFTER DELETE Clause4GL executes the AFTER DELETE clause after the user deletes a row of thescreen array. The user can delete a row by using the Delete key. When the userdeletes a row, 4GL does the following:

1. Deletes the row from the screen and program array

2. Executes the AFTER DELETE clause

3. Executes the AFTER ROW clause, if one is specified

The following AFTER DELETE clause calls the renum_items function afterdeleting a row from the screen array:

AFTER DELETECALL renum_items()

The BEFORE FIELD Clause4GL executes the BEFORE FIELD clause associated with a field whenever thecursor enters the field and before the user enters a value. You can use a NEXTFIELD statement within a BEFORE FIELD clause to restrict access to a field. Youcan also use a DISPLAY statement within a BEFORE FIELD clause to display adefault value in a field. You can specify only one BEFORE FIELD clause foreach field.

The following INPUT ARRAY statement causes 4GL to prompt the user forinput when the cursor is in the stock_num, manu_code, or quantity fields:

INPUT ARRAY p_items FROM s_items.*BEFORE FIELD stock_num

MESSAGE "Enter a stock number."BEFORE FIELD manu_code

MESSAGE "Enter the code for a manufacturer."BEFORE FIELD quantity

MESSAGE "Enter a quantity."...

END INPUT



The AFTER FIELD Clause4GL executes the AFTER FIELD clause associated with a field every time thecursor leaves the field. The cursor can leave the field if the user presses oneof the following keys:

■ Any arrow key

■ RETURN key

■ Accept key

You can specify only one AFTER FIELD clause for each field.

The following AFTER FIELD clause checks if the stock_num and manu_codefields contain values. If they do contain values, 4GL calls the get_item( )function:

AFTER FIELD stock_num, manu_codeLET pa_curr = arr_curr()IF p_items[pa_curr].stock_num IS NOT NULL

AND p_items[pa_curr].manu_code IS NOT NULL THENCALL get_item()IF p_items[pa_curr].quantity IS NOT NULL THEN

CALL get_total()END IF

END IF


The ON KEY Clause

The ON KEY Clause4GL executes the statements in the ON KEY clause whenever the user pressesone of the keys specified in key-list. You can include the following keys in key-list. Type the key names in uppercase or lowercase.

The following table lists keys that require special consideration before youassign them in an ON KEY clause.

ACCEPT INTERRUPT

DELETE LEFT

DOWN NEXTPAGE

ESC PREVPAGE

ESCAPE RIGHT

HELP TAB

INSERT UP

F1 through F64 CTRL-char(except A, D, H, K, L, R, or X)

Key Consideration

ESC orESCAPE

You must specify another key as the Accept key because ESCAPE isthe default Accept key. Reassign the Accept key in the OPTIONSstatement.

F1 You must specify another key as the Insert key because F1 is thedefault Insert key. Reassign the Insert key in the OPTIONSstatement.

F2 You must specify another key as the Delete key because F2 is thedefault Delete key. Reassign the Delete key in the OPTIONSstatement.

F3 You must specify another key as the Next key because F3 is thedefault Next key. Reassign the Next key in the OPTIONS statement.

(1 of 2)


The ON KEY Clause

You might not be able to use other keys that have special meaning toyour version of the operating system. For example, you cannot use CTRL-Z onmany BSD UNIX systems. Also, CTRL-C, CTRL-S, and CTRL-Q have specialmeanings in many UNIX systems.

4GL passes control to the statements following an ON KEY clause when theuser presses one of the listed keys. For example, the following statementdefines an ON KEY clause for the CTRL-B key. Whenever the user presses theCTRL-B key, 4GL determines if the cursor is in the stock_num or manu_codefields. If the cursor is in one of these fields, 4GL calls the stock_help functionand sets quantity as the next field.

INPUT ARRAY p_items FROM s_items.*ON KEY (CONTROL-B)


END IF

F4 You must specify another key as the Previous key because F4 is thedefault Previous key. Reassign the Previous key in the OPTIONSstatement.

INTERRUPT You must execute a DEFER INTERRUPT statement. (When the userpresses the Interrupt key under these conditions, 4GL executes thestatements in the ON KEY clause and sets int_flag to nonzero, butdoes not terminate the INPUT ARRAY statement.)

CTRL-charWhere char isA, D, H, I, J, L,M, R, X


The regular meaning of CTRL-I (TAB), CTRL-J (LINEFEED) andCTRL-M (RETURN) is lost to the user. Instead, the key is “trapped”by 4GL and used to trigger the commands in the ON KEY clause. Forexample, if CTRL-M appears in an ON KEY clause, the user cannotpress RETURN to advance the cursor to the next field. If you mustinclude one of these keys in an ON KEY clause, be careful to restrictthe scope of the clause to specific fields.

Key Consideration

(2 of 2)



After executing the statements, 4GL restores what you were doing.

If the user triggers an ON KEY clause while entering data in the field, 4GLdoes the following:


2. Preserves the input buffer that contains the characters the user hastyped


4. Restores the input buffer for the current screen field

5. Resumes input in the same field with the cursor returned to itsposition before the ON KEY keystroke was pressed

You can change this default behavior by resuming input in another field byusing the NEXT FIELD statement.

You can also use the ON KEY clause to provide accelerator keys for commonfunctions such as saving and deleting.

You can use the infield( ) function to make field-specific responses in theaction for an ON KEY clause.

The NEXT FIELD StatementBy default, 4GL moves the cursor from left to right among the screen fields.You can control the order in which the cursor visits the fields by using theNEXT FIELD statement. The NEXT FIELD statement has the following syntax:


You must specify one of the following options for the NEXT FIELD statement.

Option Purpose

NEXT Moves the cursor to the next field.

PREVIOUS Moves the cursor to the previous field.

field-name Moves the cursor to field-name.


The CONTINUE INPUT Statement

When 4GL encounters the NEXT FIELD statement, it immediately positionsthe cursor in the form. 4GL does not execute any statements that follow theNEXT FIELD statement in the clause.

The NEXT FIELD statement is most commonly used in the AFTER FIELD, ONKEY, or AFTER INPUT clauses. However, you can also include it in the BEFOREFIELD clause to restrict access to a field.

For example, the following INPUT ARRAY statement includes a NEXT FIELDstatement within an ON KEY clause. If the cursor is in the stock_num ormanu_code fields when the user presses CTRL-B, 4GL sets quantity as the nextfield:



END IF...

END INPUT

In most situations, the NEXT FIELD should appear in a conditional statement.The NEXT FIELD statement must appear in a conditional statement when itappears in an AFTER INPUT clause; otherwise, the user cannot exit the form.

The CONTINUE INPUT StatementThe CONTINUE INPUT statement skips all subsequent statements that mightappear in the current clause of the INPUT ARRAY statement and returns thecursor in the screen form at the last screen field occupied.

The CONTINUE INPUT statement is useful in situations where programcontrol is nested within multiple conditional statements and you want toreturn control to the user. It also is useful in an AFTER INPUT clause, whereyou can examine field buffers and, depending on their contents, return thecursor to the form.


The EXIT INPUT Statement

The EXIT INPUT StatementThe EXIT INPUT statement cause 4GL to do the following:

■ Skip all the statements between the EXIT INPUT and the END INPUTstatements

■ Deactivate the form

■ Resume execution at the first statement following the END INPUTstatement

If you specified an AFTER INPUT clause, 4GL does not execute the clause.

The END INPUT StatementThe END INPUT statement indicates the end of the INPUT ARRAY statement.This statement should follow the last BEFORE INPUT, AFTER INPUT, BEFOREFIELD, AFTER FIELD, or ON KEY clause. If you do not include any of theseclauses, you do not need to include the END INPUT statement.

AFTER INPUT Control BlockThe INPUT and INPUT ARRAY statements support an optional AFTER INPUTcontrol block and allow the developer to inspect, validate, save, or alter thevalues of the form field buffers. INPUT ARRAY additionally supports anAFTER ROW control block that gives the 4GL developer control over thetransition from one row of the array to another (form field traversal).


AFTER INPUT Control Block

The NEXT FIELD statement in the AFTER INPUT control block gives the 4GLdeveloper the ability to prevent the user from completing the INPUTstatement if some programmer- defined semantic criteria are not satisfied.For example, if values in the various fields in that row are in conflict, thedeveloper could detour the user back to the conflicting fields before allowingthe INPUT statement to complete, by having conditional NEXT FIELD state-ments in the AFTER INPUT block. For example:

INPUT ARRAY p_items from s_items.*...AFTER ROWLET pa_curr = arr_curr()

IF p_items[pa_curr].manu_code = "PNG" THENMESSAGE "NOTE: PNG products are currently on hold"NEXT FIELD manu_code

END IF...

END INPUT

The NEXT FIELD statement in the AFTER ROW control block, if executed, nowkeeps the user entry in the current row, with the cursor in the manu_codefield, regardless of what navigation key you use to leave that row (forexample up arrow, down arrow, TAB, RETURN, or ACCEPT).

In releases of 4GL prior to 6.03, the NEXT FIELD statement was ignored exceptto choose the active field in the target row. If the ACCEPT key was used, theNEXT FIELD was ignored because the INPUT ARRAY statement had beencompleted (except for AFTER INPUT processing, if any).


Using Functions in an INPUT ARRAY Statement

Using Functions in an INPUT ARRAY Statement4GL provides a variety of functions to use in the INPUT ARRAY statement. Forcomplete descriptions of the 4GL functions, see Chapter 5, “4GL FunctionLibraries.”

Four functions are required to keep track of the relative state of the cursor, theprogram array, and the screen array. The following table describes thesefunctions.


arr_curr( ) Returns the number of the current row within the program array.This is the row where the cursor is at the beginning of the BEFOREor AFTER ROW clause, not the row the cursor moves to afterexecution of the clause.

arr_count( ) Returns the number of rows currently stored in the program array.

scr_line( ) Returns the number of the current row within the screen array. Thisis the row where the cursor is at the beginning of the BEFORE orAFTER ROW clause, not the row the cursor moves to after executionof the clause. This number can be different from the value returnedby arr_curr( ) if the program array is larger than the screen array.

set_count( ) Takes the number of rows currently stored in the program array asan argument to set the initial value of arr_count( ).

Important: You must call this function before executing the INPUTARRAY WITHOUT DEFAULTS or DISPLAY ARRAY statement.


Using Functions in an INPUT ARRAY Statement

The functions described in the following table allow you to access fieldbuffers and keystroke buffers.

The function infield(field) returns TRUE if the current field is field and FALSEotherwise. Use this function to have 4GL make field-dependent responseswhen the user presses a key in the ON KEY clause. If you call infield(field)outside the INPUT ARRAY statement, it returns a value corresponding to thefield that was current when the INPUT ARRAY statement completed.

The following statement uses the infield function to determine if the cursoris in the stock_num or manu_code fields. If the cursor is in one of these fields,4GL calls the stock_help function and sets quantity as the next field:



END IF

For complete descriptions of the 4GL functions, see Chapter 4, “Built-inFunctions and Operators,” of the INFORMIX-4GL Reference Version 6.0.


field_touched( ) Returns TRUE when the user has “touched” (made a change to)a screen field passed as an argument to the function. Moving thecursor through a field (by using the RETURN, TAB, or arrowkeys) does not mark a field as touched. This function also doesnot register the effect of statements that appear in the BEFOREINPUT clause. For example, you can assign values to fields in theBEFORE INPUT clause without having the fields marked astouched.

get_fldbuf( ) Returns the character values of the contents of one or morefields in the currently active form.

fgl_lastkey( ) Returns an INTEGER value corresponding to the most recentkeystroke executed by the user while in the screen form.



Positioning the Cursor and Scrolling

Positioning the Cursor and ScrollingThe user can move the cursor and scroll the displayed rows by using thearrow keys and the F3 and F4 function keys. The following table describeseach of these methods.

Inserting and Deleting RowsThe user can insert rows into the middle of existing rows of the record arrayby pressing the Insert key. The Insert key inserts a blank row at the currentlocation and moves the cursor to the beginning of the blank row. The userdoes not need to use the Insert key to insert rows at the end of the recordarray. The user simply types in the information.

If the user attempts to insert rows beyond the defined size of the record array,4GL displays a message that the array is full.

Key Purpose

[→] Moves the cursor one space to the right inside a screen field withouterasing the current character. At the end of the screen field, 4GL moves thecursor to the first character position of the next screen field. The [→] keyis equivalent to the CTRL-L editing command.

[←] Moves the cursor one space to the left inside a screen field without erasingthe current character. At the end of the screen field, 4GL moves the cursorto the first character position of the previous screen field. The [←] key isequivalent to the CTRL-H editing command.

[↓] Moves the cursor to the same display field one row down on the screen.If the cursor was on the last row of the screen array before the user pressed[↓], 4GL scrolls the program array data up one row.

[↑] Moves the cursor to the same display field one row up on the screen. If thecursor was on the first row of the screen array before the user pressed [↑],4GL scrolls the program array data down one row.

F3 Scrolls the display to the next full page of program array rows. You canreset this key by using the NEXT KEY clause of the OPTIONS statement.

F4 Scrolls the display to the previous full page of program array rows. Youcan reset this key by using the PREVIOUS KEY clause of the OPTIONSstatement.


Editing During an INPUT ARRAY Statement

The user can delete the current row by pressing the Delete key. 4GL adjuststhe subsequent rows to fill the gap.

The default Insert key is the F1 function key. The default Delete key is F2. Youcan alter the default keys by using the OPTIONS statement.

Editing During an INPUT ARRAY StatementYou can use the keys shown in the following table for editing during anINPUT ARRAY statement.

Completing an INPUT ARRAY StatementThe following conditions can terminate the INPUT ARRAY statement:


❑ The Accept key


❑ The Quit key

■ 4GL executes the EXIT INPUT statement.

All of these conditions deactivate the form. Unlike the INPUT statement, theINPUT ARRAY statement is not terminated when the user presses the RETURN

or TAB key at the last screen field.

Key Purpose

CTRL-A Toggles between insert and typeover mode.

CTRL-D Deletes characters from the current cursor position to the end of the field.

CTRL-H Moves the cursor one space to the left inside a field. It is equivalent topressing the [←] key.

CTRL-L Moves the cursor one space to the right inside a field. It is equivalent topressing the [→] key.

CTRL-R Redisplays the screen.

CTRL-X Deletes the character beneath the cursor.


Completing an INPUT ARRAY Statement

By default, both the Accept key and the Interrupt key complete the INPUTARRAY statement. However, an Interrupt or Quit also terminates theprogram immediately.



■ Terminate the INPUT ARRAY statement but not the 4GL program



■ Terminate the INPUT ARRAY statement but not the 4GL program.

When INPUT ARRAY terminates, 4GL executes the following clauses in theorder indicated:

1. The AFTER FIELD clause of the current field

2. The AFTER ROW clause

3. The AFTER INPUT clause

If INPUT ARRAY terminates by an EXIT INPUT statement, 4GL does notexecute any of these clauses. If a NEXT FIELD statement appears in one ofthese clauses, 4GL places the cursor in the specified field and returns controlto the user.

ExampleThe following INPUT ARRAY statement helps a user enter values in a screenform. The BEFORE FIELD clauses display messages telling the user what toenter in the stock_num, manu_code, and quantity fields. The AFTER FIELDclauses check that user entered values for the stock_num, manu_code, andquantity fields. When values are specified for the stock_num andmanu_code fields, 4GL calls get_item( ) to display the description and priceof the chosen item. When all three fields are specified, 4GL displays the totalcost.


Completing an INPUT ARRAY Statement

The BEFORE INSERT, AFTER INSERT, and AFTER DELETE clauses call functionsthat ensure the numbering of the items is accurate. This is necessary becausethe user can use the Insert and Delete keys to insert and delete items withinthe screen form.

INPUT ARRAY p_items FROM s_items.*BEFORE FIELD stock_num

MESSAGE "Enter a stock number."

BEFORE FIELD manu_codeMESSAGE "Enter the code for a manufacturer."

BEFORE FIELD quantityMESSAGE "Enter a quantity"

AFTER FIELD stock_num, manu_codeMESSAGE ""LET pa_Curr = arr_curr()IF p_items[pa_curr].stock_num IS NOT NULL

AND p_items[pa_curr].manu_code IS NOT NULL THENCALL get_item()IF p_items[pa_curr].quantity IS NOT NULL THEN


END IF

AFTER FIELD quantityMESSAGE ""LET pa_curr = arr_curr()IF p_items[pa_curr].stock_num IS NOT NULL

AND p_items[pa_curr].manu_code IS NOT NULLAND p_items[pa_curr].quantity IS NOT NULL THEN


BEFORE INSERTCALL get_item_num()

AFTER INSERTCALL renum_items()

AFTER DELETECALL renum_items()

END INPUT

Related StatementsDISPLAY ARRAY, INPUT, OPTIONS


LOAD Statement Transaction Management

LOAD Statement Transaction ManagementThis section describes LOAD transaction management issues. For completedocumentation on use of the LOAD statement, see pages 3-180 to 3-184 of theINFORMIX-4GL Reference Version 6.0.

When the current database uses transaction logging, Version 6.01 (and higherin the 6.0 family) of 4GL give you better control over LOAD statement runtimeerrors than did previous releases.

If the database has no transaction log, a failing LOAD statement cannotremove any rows that were loaded before the failure occurred. You mustmanually remove the already loaded records from either the load file or thereceiving table, repair the erroneous records, and rerun the LOAD. This is truefor all versions of 4GL.

The remainder of this section pertains only to databases with transactionlogs; there is no change to LOAD in the 6.01 and higher releases in the 6.0 4GLfamily that affects unlogged databases.

In versions prior to 6.01, if the database has a transaction log and atransaction is in effect before the LOAD statement executes, LOAD alwaysCOMMITs the transaction as the LOAD statement completes. The user cannotcontrol or prevent this internal COMMIT.

Beginning with Version 6.01, you can do one of the following when thedatabase has a transaction log:

■ Run the LOAD as its own transaction, so that any error causes theentire LOAD statement to be automatically rolled back (implicittransaction).



■ Run the LOAD within an explicit transaction, so that a data errormerely stops the LOAD statement in place with the transaction stillopen.

Running the LOAD within an explicit transaction allows you to doone of the following:

❑ COMMIT the successfully loaded rows, fix the load records, andrerun LOAD with the balance of the records.

❑ Abort the LOAD attempt altogether by executing a transactionROLLBACK, followed by a re-run of the LOAD task from thebeginning.

In versions 6.01 and higher, LOAD does not execute a COMMIT or ROLLBACKstatement unless the LOAD statement was the first statement of a new(implicit) transaction.

For example, if the database is MODE ANSI, a transaction is always in effect.LOAD would be the first statement of a new transaction only if the immedi-ately preceding SQL statement was a DATABASE statement, a COMMITstatement, or a ROLLBACK statement.

If the database is not MODE ANSI but has a transaction log, a new transactionis indicated by a BEGIN WORK statement. LOAD is the first statement of a newtransaction only if the immediately preceding SQL statement was a BEGINWORK statement.

If LOAD executed successfully, the following confirmation message appears:

xxxx row(s) loaded.

If LOAD did not execute successfully, an error number and message appear.The message shows the line number of the offending record in the LOAD file.

In either type of logged database, if LOAD is the first statement of a new(implicit) transaction, it automatically performs a COMMIT WORK statementif the load completes without errors. If, instead, errors are found during theLOAD, a ROLLBACK WORK statement is automatically performed. Thus, theLOAD creates its own transaction and succeeds or fails as a unit. If errorsoccur, the automatic ROLLBACK WORK statement restores the table to its statebefore the LOAD was attempted.



In either type of logged database, if LOAD is not the first statement of a newtransaction, the LOAD leaves the transaction open and performs neither aCOMMIT WORK nor a ROLLBACK WORK automatically. If the LOADcompletes without errors, the user typically runs the COMMIT WORKstatement to complete the transaction. If an error occurs during the LOADstatement, you must take one of the following actions:

■ COMMIT the successfully loaded rows, fix the LOAD records, andrerun LOAD with the balance of the records.

■ Abort the LOAD attempt altogether by executing a transactionROLLBACK and rerun the LOAD task from the beginning.

The following 4GL script fragment illustrates a typical LOAD statement seriesusing an explicit transaction in a non-MODE ANSI database:

create database mine with log in "/db/mine/trans.log";create table mytab1 (col1 serial, col2 char(20), col3 date);create table loadlog (tabname char(18), loaddate date);begin work;insert into loadlog values ("mytab1", today);load from "mytab1.unl" insert into mytab1;

If the LOAD is successful, at this point you can execute COMMIT WORK orROLLBACK WORK as appropriate.

The next 4GL script fragment illustrates the same steps using an explicittransaction in a MODE ANSI database:

create database mine_ansi with log in "/db/mine/trans.log" MODE ANSI;create table "user1".mytab1 (col1 serial, col2 char(20), col3 date);create table "user1".loadlog (tabname char(18), loaddate date);commit work;insert into "user1".loadlog values ("mytab1", today);load from "mytab1.unl" insert into "user1".mytab1;

If the LOAD is successful, at this point you can execute COMMIT WORK orROLLBACK WORK as appropriate.

The third 4GL script fragment illustrates a typical LOAD statement (with animplicit transaction) in a non-MODE ANSI database:

create database mine with log in "/db/mine/trans.log";create table mytab1 (col1 serial, col2 char(20), col3 date);close database;database mine;load from "mytab1.unl" insert into mytab1;



If the LOAD has no errors, the changes are committed. If error messagesappear, the rows loaded before the error occurred are rolled backautomatically.

The final 4GL script fragment illustrates a typical LOAD statement (withimplicit transaction) in a MODE ANSI database:

create database mine_ansi with log in "/db/mine/trans.log" MODE ANSI;create table "user1".mytab1 (col1 serial, col2 char(20), col3 date);close database;database mine_ansi;load from "mytab1.unl" insert into "user1".mytab1;

If the LOAD has no errors, the changes are committed. If error messagesappear, the rows loaded before the error occurred are rolled backautomatically.


MENU

MENUUse the MENU statement to create a menu screen, define menu options,designate help numbers, and define the statements to execute for eachoption.

Syntax

MENU menu-name{

{BEFORE MENU|COMMAND

{KEY (key-list)|[KEY (key-list)] menu-option

[option-description][HELP help-number]

}}{statement|CONTINUE MENU|EXIT MENU|NEXT OPTION menu-option|SHOW OPTION {option-list | ALL}|HIDE OPTION {option-list | ALL}} ...

} ...END MENU

MENU is a required keyword.

menu-name is a character variable or quoted string constant containing thetitle of the menu.

(1 of 3)


MENU

BEFOREMENU

is an optional clause containing one or more 4GL statements.4GL executes these statements once before displaying themenu.

COMMAND is a required keyword.

KEY is an optional keyword.


■ F1 through F64

■ CTRL-char, where char is a letter


DELETE, ACCEPT, ESCAPE, ESC, INTERRUPT, HELP, TAB, orRETURN.

For specific limitations on key-list, see the section titled “TheKEY Clause” on page 103.

menu-option is a character variable or quoted string constant containing thetitle of the menu option.

option-description

is a character variable or quoted string constant describingmenu-option. This string appears on the line below the menuwhenever menu-option is highlighted.

HELP is an optional keyword.

help-number is the number of the help message in the help file (designatedin the OPTIONS statement) that corresponds to menu-option.

statement is a 4GL statement to execute when the user selects the option.Several statements can exist for an option, includingCONTINUE MENU, EXIT MENU, NEXT OPTION, HIDE OPTION,and SHOW OPTION.

CONTINUEMENU

is an optional statement that returns program control to thecurrent MENU statement.

EXIT MENU is an optional statement that causes program control to moveto the first 4GL statement following the END MENU keywords.

(2 of 3)


MENU

General UsageThe MENU statement specifies a menu name, one or more options, and theactions (4GL statements) associated with each option.

When 4GL displays a menu, it adds a colon (:) and a space after the menuname, as well as a space before and after each menu option. If the width ofthe menu exceeds the number of characters that the screen or a window candisplay on a single line, 4GL displays the first “page” of options followed byan ellipsis (. . .) indicating that additional options exist.

NEXTOPTION

is an optional statement that indicates the menu option thatyou want highlighted when you return to the menu.

HIDEOPTION

is an optional statement that hides the options listed in option-list.

SHOWOPTION

is an optional statement that displays the options listed inoption-list.

option-list is a list of character variables or quoted option names,separated by commas.

ALL is an optional keyword that causes 4GL to show or hide all themenu options.

END MENU is a required statement that terminate the MENU statement.

(3 of 3)

menu-name: menu-option1 menu-option2 menu-option3 menu-option4 ...Description of menu-option1.


MENU

The user can press SPACEBAR or [→] to move past the rightmost option(menu-option4 in this case); 4GL displays the next page of menu options. Inthe following example, the ellipses at each end indicate that more menuoptions exist in both directions.

If the user moves the highlight to the right past menu-option8 in thisexample, 4GL displays a page of menu options like the following.

Since no ellipsis appears to the right of the menu, the user has come to the lastpage of the menu options. The user can display the previous page of menuoptions again by using [←] to move the highlight past the leftmost menuoption. The user can display the first page of menu options by using [→] tomove the highlight past the rightmost menu option.

[↑] moves the highlight to the first item on the previous page; [↓] moves thehighlight to the first item on the subsequent page.

After the user chooses an option, 4GL executes the statements immediatelyfollowing the COMMAND clause. After 4GL executes all the statements for anoption, it redisplays the menu, and the user can choose another option.

4GL ordinarily displays the menu starting at line 1 on the window. You canspecify an alternate line in the OPTIONS statement or (if the menu appears ina window) in the ATTRIBUTES clause of the OPEN WINDOW statement.

menu-name: ... menu-option5 menu-option6 menu-option7 menu-option8 ...Description of menu-option5.

menu-name: ... menu-option9 menu-option10 menu-option11Description of menu-option9.


The BEFORE MENU Clause

The BEFORE MENU Clause4GL executes statements that appear in the BEFORE MENU clause once beforedisplaying the menu. For example, in the BEFORE MENU clause you can:

■ specify values for variables used for the menu name, the names ofoptions, and option descriptions.

■ hide and show selected menu options.

The following BEFORE MENU clause initially hides all menu options. If theuser is privileged, 4GL then displays all the menu options. If the user is notprivileged, 4GL displays only the Query, Detail, Switch, and Exit menuoptions:

MENU menu_nameBEFORE MENU

HIDE OPTION ALLIF priv THEN

LET menu_name = "PRIVILEGED SEARCH"SHOW OPTION ALL

ELSESHOW OPTION "Query", "Detail", "Switch", "Exit"

END IF...

END MENU

The COMMAND ClauseThe menu screen displays each menu-option in a ring menu in the order thatthe COMMAND clauses appear in the MENU statement.

4GL produces a runtime error if a menu option or menu option descriptionexceeds the length of the screen or the current window.

You can add an “invisible” option to your menu by including a KEY key-listchoice, without a command name, in the list of menu options. This is demon-strated in the example at the end of this section.

Optionally, you can include a description of the menu option in a COMMANDclause. The description appears on the line below the menu and is displayedwhen the option is highlighted.

You can use a CHAR variable to specify an option name or an optiondescription. 4GL produces a runtime error if the defined length of the variableexceeds the length of the screen or the current window.


The KEY Clause

The KEY ClauseYou can use the KEY clause to specify one or more keys that 4GL associateswith an option. The user must then type one of these keys to choose theoption. If the KEY clause is not present, the user chooses an option by typingthe first letter(s) of the option name. Note that, when you assign a key to anoption, the first letter no longer activates the option.

The key-list notation to specify function keys is F1 through F64. The notationfor control keys is CTRL-char, where char is any letter except A, D, H, I, J, K, L,M, R, or X. (Some other keys, such as S, Q, or Z also might not be allowed,depending on your implementation of UNIX.)

The key-list notation for the ESCAPE key is ESC or ESCAPE. The notation for theInterrupt key (often the DEL or CTRL-C key) is INTERRUPT.

The HELP StatementYou can use the HELP help-number statement to provide a more detaileddescription of an option. The help-number refers to the number of the helpmessage in the help file set by the OPTIONS statement. This message appearswhen the option is highlighted and the user presses the Help key.

A runtime error occurs if you specify a help-number for an option and thatnumber does not occur in the help file, or if the help file does not exist.

The CONTINUE MENU StatementYou can execute a CONTINUE MENU statement anywhere within thestatements following the COMMAND clause. This statement causes the menuto reappear so that the user can choose another option.


The EXIT MENU Statement

The EXIT MENU StatementWhen 4GL encounters the EXIT MENU statement, 4GL does the following:

■ Skips all statements between the EXIT MENU statement and the ENDMENU statement

■ Deactivates and erases the menu from the screen

■ Resumes execution of the first statement following the END MENUstatement

Use this statement to leave the menu rather than redisplaying the menu. Youshould specify this statement for at least one menu option in each menu;otherwise, the user will have no way to leave the menu.

The following example demonstrates using the EXIT MENU statement from amenu option named “Exit”:

MENU "CUSTOMER"...COMMAND "Exit" "Leave the CUSTOMER menu."

EXIT MENUEND MENU

The NEXT OPTION StatementWhen 4GL finishes executing the statements in a COMMAND clause,4GL keeps the option just executed as the current option. If you want adifferent current option, use the NEXT OPTION statement. The NEXT OPTIONstatement identifies the menu option to make current; it does not select thenext menu option. To select the current option, the user presses RETURN.


The SHOW OPTION and HIDE OPTION Statements

In the following MENU statement, if the user selects the Query option,4GL executes the function query_data( ) and then redisplays the menu withModify as the current option. The user can select the Modify option bypressing RETURN. Without this NEXT OPTION statement, 4GL would displayQuery as the current option, and the user would have to make Modify thecurrent option and then press RETURN.

MENU "CUSTOMER"COMMAND "Query" "Search for a customer"

CALL query_data()NEXT OPTION "Modify"

...COMMAND "Modify" "Modify a customer"

...END MENU

The SHOW OPTION and HIDE OPTION StatementsBy default, 4GL displays all menu options. When you want to display asubset of the menu options, you should use the HIDE OPTION statement andthe SHOW OPTION statement to specify which options appear on a menu. Usethe ALL keyword to display all the menu options.

4GL does not display a hidden option, and it treats a keystroke that wouldselect the option (if it were visible) as an invalid entry.

Hidden options remain hidden until you exit the MENU statement or executea SHOW OPTION statement.

4GL displays the menu options in the order that the COMMAND clausesappear in the MENU statement. The order in which options are listed in theSHOW OPTION statement is irrelevant.

The HIDE OPTION statement does not affect any “invisible” commands(commands that are assigned a KEY but not a command name) included inthe MENU statement, since these options are always invisible to the user. Youmust use another approach (for example, place their actions within a condi-tional statement) to enable and disable these options.


The END MENU Statement

The following example MENU statement populates a menu with eightoptions. The Long_menu option shows all options; the Short_menu optionshows only the Query, Details, Long_menu, and Exit options.

MENU "Order Management"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 current order"

CALL det_order()COMMAND "Long_menu" "Display all menu options"

SHOW OPTION ALLCOMMAND "Short_menu" "Display a short menu"

HIDE OPTION ALLSHOW OPTION "Query", "Details", "Long_menu", "Exit"

COMMAND "Exit" "Exit the Order Management Form"EXIT MENU

END MENU

The HIDE OPTION and SHOW OPTION statements can appear in a BEFOREMENU clause or in a COMMAND clause.

You must assign a value to a variable used to specify a menu option beforeyou can include the variable in a HIDE OPTION statement.

The END MENU StatementUse the END MENU statement to indicate the end of the MENU statement. TheEND MENU statement should follow the last COMMAND clause of the menu.The END MENU statement is required.

Choosing a Menu OptionThe user chooses a menu option in one of three ways:

■ Positioning the highlight on the option and pressing RETURN

■ Typing one of the keys associated (in the KEY clause) with the option

■ Typing the first letter(s) of the option name


Choosing a Menu Option

When the user types a letter, 4GL looks for a unique match among the menuoptions. If only one option begins with the letter, or only one option isassociated (in a KEY clause) with the letter, the choice is unambiguous and4GL executes the commands associated with the option. If more than oneoption begins with the letter, 4GL clears the second line of the menu andprompts the user to clarify the choice. 4GL displays each keystroke, followedby the names of the menu options that begin with the typed letters. When4GL identifies a unique option, it closes this prompt line and executes thestatements associated with the selected menu option.

For example, the next menu includes three options that begin with the lettersMa. The following screen is displayed when the user types the letter M:

When the user types the letters Mal, 4GL drops Manteca from the list anddisplays the two remaining options.

At this point, the user can type an a to select Malay or a t to select Malta.

The Arrow keys have no effect when choosing among menu options thatbegin with the same letters. BACKSPACE deletes the keystroke to the left of thecursor.

Resorts: Oxnard Malay Malta Manteca Pittsburgh PortugalSelect: M Malay Malta Manteca

Resorts: Oxnard Malay Malta Manteca Pittsburgh PortugalSelect: Mal Malay Malta


Using Variables in a MENU Statement

Using Variables in a MENU StatementYou can use a CHAR variable as a menu name, an option name, and as anoption description. Variable assignments can appear before 4GL executes theMENU statement or within the MENU statement. You can specify variablevalues in the BEFORE MENU clause and one or more of the COMMANDclauses in a MENU statement. The final example at the end of this sectionillustrates this feature.

The following notes apply when you change the value of a variable used asthe menu name or an option name in a COMMAND clause of a MENUstatement:

■ 4GL determines the length of the menu name and each option nameat the time it first displays the menu. This length does not changeover the duration of the MENU statement.

If you subsequently specify a new value for a variable, 4GL displaysas much of the new value as will fit in the existing space.

For example, suppose 4GL displays Short_Menu (10 characters) asa menu title. If a COMMAND clause specifies the new valueVery_Long_Menu (14 characters) as the variable used for the menutitle, 4GL displays the first ten characters of the new title only.

Similarly, if a second COMMAND clause specifies the value Menu(four characters) as the menu title, 4GL displays the new title with sixtrailing blank spaces.

4GL truncates a new menu title if it exceeds the length of the originaltitle, and pads a new menu title with blanks if it occupies less spacethan the original title.

■ When you subscript into an array to specify one or more variablevalues, a change to the index into the array does not change thevariable values.

Values returned from the array are used for the duration of theMENU statement. Any subsequent change to the index into the arraywill not affect the values used in the MENU statement.

4GL produces a runtime error if the defined length of a variable used tospecify a menu name, an option name, or an option description exceeds thelength of the screen or the current window.



You must assign a value to a variable that specifies an option name beforeyou can include the variable in a HIDE OPTION statement.

ExampleThe following MENU statement uses variables for the menu name,a command name, and an option description:

DEFINE menu_name, command_name CHAR(10),option_desc CHAR(30),priv_flag SMALLINT

LET menu_name = "NOVICE"LET command_name = "Expert"LET option_desc = "Display all menu options."

IF ... THENLET priv_flag = 1

END IF

MENU menu_name

BEFORE MENUHIDE OPTION ALLIF priv_flag THEN -- expert user

LET menu_name = "EXPERT"LET command_name = "Novice"LET option_desc = "Display a short menu."SHOW OPTION ALL

ELSE -- novice user

SHOW OPTION "Query", "Detail", "Exit", command_nameEND IF

COMMAND "Query" "Search for rows." HELP 100CALL get_cust()

COMMAND "Add" "Add a new row." HELP 101CALL add_cust()

COMMAND "Update" "Update the current row." HELP 102CALL upd_cust()NEXT OPTION "Query"

COMMAND "Delete" "Delete the current row." HELP 103CALL del_cust()NEXT OPTION "Query"

COMMAND "Detail" "Get details." HELP 104CALL det_ord()NEXT OPTION "Query"



COMMAND command_name option_desc HELP 105IF priv_flag THEN -- EXPERT menu visible

LET menu_name = "NOVICE"LET command_name = "Expert"LET option_desc = "Display all menu options."HIDE OPTION ALL

SHOW OPTION "Query", "Detail", "Exit", command_nameLET priv_flag = 0

ELSE -- NOVICE menu visibleLET menu_name = "EXPERT"LET command_name = "Novice"LET option_desc = "Display a short menu."SHOW OPTION ALLLET priv_flag = 1

END IF

COMMAND KEY ("!")CALL bang()

COMMAND "Exit" "Leave the program." HELP 106EXIT MENU

END MENU

These statements produce both an expert menu and a novice menu:

EXPERT: Query Add Update Delete Detail Novice ExitSearch for rows.

NOVICE: Query Detail Expert ExitSearch for rows.


Keys in a Command Key Clause

Keys in a Command Key ClauseThe MENU statement has a limit of four keys per command clause that can bebound to a given COMMAND KEY() clause.

For example:

MENU "Main Menu"COMMAND "Option 1" "Option 1 Description"...COMMAND KEY("a", "up", CONTROL-F, F35) {LEGAL}...COMMAND KEY("b", "down", CONTROL-B, F36, F10) {ILLEGAL - 5 keys}...

If you exceed this limit, the 4GL Rapid Development System (RDS) returnserror -4457 at pcode compile time. Compiled 4GL (c4gl) returns an error atphase 2 of the compile of the form:

i4glc2: file "cmkey.ec", line 31: You may have at most 4 keysin the key list

MENU COMMAND KEY ConflictsIn previous releases, the runtime MENU code gave inconsistent visual resultsand hung menus if a conflict existed between multiple COMMAND KEYclauses or between a COMMAND KEY clause and a COMMAND clause.

Because single keystroke immediately activates the statements in aCOMMAND KEY code structure (without waiting for you to press RETURN), nogiven key definition used in a COMMAND KEY clause may logically appearmore than once in a particular menu. However, nothing in the runtime codechecked for such a programming error, and confusing prompts might beissued to the user if such an error existed in a menu.

The following examples illustrates the improper coding methods and typicalruntime results. First, a conflict between COMMAND KEY clauses:

MENU "main 1"COMMAND KEY (F3, "a")

MESSAGE "This is F3 or <a> only"SLEEP 1

COMMAND KEY (F3, CONTROL-F)MESSAGE "This is F3 or CONTROL-F"SLEEP 1


MENU COMMAND KEY Conflicts

If you pressed the F3 key while this menu was active, the program entered anerror state from which you could not recover. A submenu of the style used toresolve collisions on COMMAND clauses (as opposed to COMMAND KEYclauses) appeared inappropriately with two “invisible” prompts, thus:

Select: \072 (invisible) (invisible)

It always produced two (“invisible”) prompts, regardless of how many keyswere acceptable to the COMMAND KEY clause. Any subsequent keystrokeonly yielded the terminal bell, and the program had to be killed with a signal(such as the interrupt or kill key).

If instead there is a collision between a COMMAND clause and a COMMANDKEY clause (where the first character of the COMMAND string, whether thestring is a constant or a variable, collided with a printable character recog-nized by a COMMAND KEY clause), and the colliding keystroke occurred (bin the following example), a submenu appeared with one side showing“invisible”:

MENU "main 1"COMMAND KEY (F3, "a", F22, F23)

MESSAGE "This is F3, <a>, F22, or F23 only"SLEEP 1

COMMAND KEY (F4, "b")MESSAGE "This is F4 or <b> only"SLEEP 1

COMMAND "bark" "collides with command key (f4, b)"MESSAGE "This collides with command key (f4, b)"SLEEP 1

...

If the proper second letter was pressed (in this case), the menu proceedednormally; any other keystroke simply activated the terminal bell.

Now the runtime menu library detects such collisions. If such a conflictoccurs, error -1176, A COMMAND KEY value occurs elsewhere in thecurrent menu, is returned and the program terminates.

Implications for Users Upgrading From Earlier Releases

If you encounter error -1176, it means that a COMMAND KEY conflict alreadyexists in that menu. You need to revise the offending COMMAND KEY clausesto remove the conflict.


PROMPT

PROMPTIn current releases of 4GL, you need to ensure that the length of the displaylist for the PROMPT statement is smaller than the number of columns on theactive window. If the display list is greater than or equal to the number ofcolumns, then error -1146 is generated at runtime.

OPTIONS PROMPT LINE Default BehaviorIf the value you specify for the PROMPT LINE, using the OPTIONS statement,exceeds the number of rows on the active window then PROMPT LINE is setto its default value, that is, the first row of the window. The following 4GLcode increments the value of the PROMPT LINE in the WHILE loop:

MAIN

DEFINE ans CHAR(1)DEFINE pline INTEGERDEFINE flag CHAR(1)

LET pline = 7OPTIONS PROMPT LINE pline

WHILE pline <> 10OPEN WINDOW wdw AT 4,6 WITH 7 ROWS, 60 COLUMNS ATTRIBUTE (BORDER)DISPLAY " winrowsize = 7, PROMPT LINE is set to ", pline at 2, 6PROMPT "123456789012345678901234567890abcdef" FOR CHAR ansCLOSE WINDOW wdwLET pline = pline + 1OPTIONS PROMPT LINE pline

END WHILE

END MAIN


OPTIONS PROMPT LINE Default Behavior

Note the following aspects of this 4GL code example:

1. The variable pline is initialized to 7 and PROMPT LINE is set to thevalue held in pline.

2. A window with 7 rows and 70 columns is opened within WHILE loopand the value of pline is incremented.

3. The user tries to set PROMPT LINE to 8 using OPTIONS statement.

4. While opening the window in the next iteration, 4GL notices that thevalue of PROMPT LINE is greater than the maximum number of rowsavailable.

5. Therefore, 4GL silently sets the value of PROMPT LINE to the defaultvalue, that is, the first row of the window.


UNLOAD

UNLOADThe UNLOAD statement now supports host variables in the WHERE clause ofthe embedded SELECT query. The previously recommended workaround forthis problem, which dynamically builds the SELECT statement for UNLOAD,is still valid. Following is an example of the workaround that was earlierrecommended:

DATABASE stores

MAIN

DEFINE hostvar SMALLINTDEFINE tempsel CHAR(200)

LET hostvar = 103LET tempsel = "select * from customer ",

"where customer_num = ", hostvar

UNLOAD TO "custfile" DELIMITER ";" tempsel

END MAIN

Now you can code the UNLOAD statement as follows:

DATABASE stores

MAIN

DEFINE hostvar SMALLINT

LET hostvar = 103UNLOAD TO "custfile" DELIMITER ";"

SELECT * FROM customer WHERE customer_num = hostvar

END MAIN


UNLOAD

Do not substitute question marks (?) in place of the host variables to make theSELECT statement dynamic, because it has binding problems. The following4GL code is an example of this:

FUNCTION func_unload()

DEFINE query CHAR(250)DEFINE file CHAR(20)DEFINE del CHAR(1)DEFINE i INTEGER, j INTEGER, k INTEGER

LET i = 100LET j = 30LET k = 400LET del = ";"LET file = "/dev/tty"

LET query = "select * from systables where tabid >= ?"" and ncols >= ? and rowsize >= ?"

UNLOAD TO file DELIMITER del query

END FUNCTION

The rectified version of the function func_unload() appears as:

FUNCTION func_unload()

DEFINE file CHAR(20)DEFINE del CHAR(1)DEFINE i INTEGER, j INTEGER, k INTEGER

LET i = 100LET j = 30LET k = 400LET del = ";"LET file = "/dev/tty"

UNLOAD TO file DELIMITER delSELECT * FROM Systables

WHERE tabid >= i AND ncols >= j AND rowsize >= k

END FUNCTION


UNLOAD

For applications that use the UNLOAD statement in 4GL and RDS, recompilethem with current compilers and relink them with current libraries. This isnecessary because current 4GL and RDS compilers generate different C-codeand p-code for UNLOAD than did Version 4.11 and earlier compilers.

Warning: If you do not recompile modules containing UNLOAD statements, aruntime error appears similar to the following:

Program stopped at "try.4gl", line number 8. 4GL run-timeerror number -4520. Module "" in the pcode file containspcode version 8. This program can run pcode version 625832.Run the pcode compiler with "-V" to check the pcode versionthat it produces and then recompile all modules of yourprogram and run it again.

The actual version reported might differ from the value 625832.


7Chapter

Environment Variables

C4GLFLAGS and FGLPCFLAGS . . . . . . . . . . . . . . 7-4

C4GLNOPARAMCHK . . . . . . . . . . . . . . . . . 7-5

DBESCWT . . . . . . . . . . . . . . . . . . . . . . 7-7

FGLSKIPNXTPG . . . . . . . . . . . . . . . . . . . 7-8

INFORMIXDIR . . . . . . . . . . . . . . . . . . . . 7-8

INFORMIXTERM . . . . . . . . . . . . . . . . . . . 7-9

IXOLDFLDSCOPE . . . . . . . . . . . . . . . . . . . 7-10

LINES and COLUMNS . . . . . . . . . . . . . . . . . 7-12

PROGRAM_DESIGN_DBS . . . . . . . . . . . . . . . . 7-14

SUPOUTPIPEMSG . . . . . . . . . . . . . . . . . . . 7-15

7-2 INFO

his chapter describes the following new environment variables:


■ C4GLNOPARAMCHK

■ DBESCWT

■ FGLSKIPNXTPG

■ IXOLDFLDSCOPE

■ LINES and COLUMNS

■ PROGRAM_DESIGN_DBS

■ SUPOUTPIPEMSG

This chapter clarifies the use of the following environment variables:

■ INFORMIXDIR

■ INFORMIXTERM

The information on INFORMIXDIR and INFORMIXTERM supplements thedescription of these environment variables in Appendix C of the INFORMIX-4GL Reference Version 6.0. You might want to make a note in Appendix C torefer to this supplement for additional information on using theseenvironment variables.

T

Environment Variables 7-3

C4GLFLAGS and FGLPCFLAGS

C4GLFLAGS and FGLPCFLAGSThe environment variables C4GLFLAGS and FGLPCFLAGS allow you to setcertain compiler options as defaults. These options simplify many compila-tions. Typical values are:

Informix recommends compiling all 4GL programs with -anyerr specified.If you are using compiled 4GL and your port supports shared libraries, youcan improve system performance by using the -shared option.

-a C4GLFLAGS only

-ansi C4GLFLAGS and FGLPCFLAGS

-anyerr C4GLFLAGS and FGLPCFLAGS

-shared C4GLFLAGS only

-z C4GLFLAGS and FGLPCFLAGS


C4GLNOPARAMCHK

C4GLNOPARAMCHKC4GLNOPARAMCHK is a new environment variable which, if set, turns offthe error checking on the number of arguments passed into a routine and onthe number of values returned from it. By default, these are now checked asstringently in compiled 4GL as they are in the Rapid Development System(RDS).

Compiled 4GL has always been different from RDS in how it checks thenumber of arguments passed to a function and the number of valuesreturned from a function. RDS requires the number of arguments passed andthe number of values returned to be correct. By default, I4GL now checks thenumber of arguments and number of return values, and generates a fatalerror if the numbers are incorrect. Any code that worked under RDS workswith the new compiled code; only code that did not work under the p-codesystem fails. You can disable this checking mechanism by setting the newenvironment variable C4GLNOPARAMCHK at compile time. The variablename C4GLNOPARAMCHK must be set and exported in the userenvironment at compile time—it can have any value or no value.

The ability to turn off parameter checking via C4GLNOPARAMCHK isprovided as a migration aid only; it helps 4GL developers locate and correctparameter mismatches over time. This ability will be removed in a futurerelease, leaving the strict parameter checking behavior as the only functional4GL behavior.


C4GLNOPARAMCHK

The following behavior occurs:

■ If the C4GLNOPARAMCHK environment variable is not set, allfunction calls and returns are checked, and a fatal error is generatedif there is a mismatch in the number of parameters passed orreturned.

■ If the C4GLNOPARAMCHK environment variable is set at 4GLcompile time and AnyError error scope is not in effect, parametercount checking code is not generated.

■ If the C4GLNOPARAMCHK environment variable is set at 4GLcompile time and AnyError Error Scope is in effect, and if the erroraction is CONTINUE, no parameter count checking is generated; forany other error actions (such as STOP, GOTO, or CALL), the parametercount checking code is generated.

Tip: If you are unfamiliar with error scopes, see “Handling 4GL Runtime Errors” onpage 3-25.


DBESCWT

DBESCWTThis environment variable controls the way INFORMIX-4GL productsinterpret the sequence of characters that the function and arrow keys send onsome types of terminals. When you press a function key or an arrow key,many terminal types send a sequence of characters that starts with the ESC

character. 4GL uses the ESC character as the ACCEPT key, so that after readingan ESC character, the software must read the next character to see whether itis one of those that make up a function or arrow key sequence. If the machineor network is very slow, the software might interpret a function keykeystroke as a distinct ESC character later followed by one or more charactersechoed to the screen. DBESCWT lets you configure the delay.

Syntax

You set DBESCWT to a value between 1 and 60, indicating the number ofseconds that the software waits after it receives the ESC character from thekeyboard before it decides that you have hit ESC rather than a function orarrow key. The default wait time is one second.

Function and arrow keys normally generate escape sequences faster thana typist can type so that the application can make a distinction between thespecial keys and the user typing the characters in the escape sequence.

You should only use DBESCWT on systems with poor response times orwhere the software is misinterpreting arrow and function key sequences.DBESCWT slows the performance of your 4GL application.

C shell Bourne or Korn shell

setenv DBESCWT num DBESCWT=numexport DBESCWT

num is a value, in seconds, between 1 and 60.


FGLSKIPNXTPG

FGLSKIPNXTPGThe SKIP TO TOP OF PAGE command now has no effect when a report isalready at the top of the page (that is, when no data has yet been sent to a newpage). Users who rely on the older behavior of SKIP TO TOP OF PAGE canoverride this effect using the environment variable FGLSKIPNXTPG.

If you set FGLSKIPNXTPG to any value at report execution time, then SKIP TOTOP OF PAGE forces a page change even if no data has yet been printed in thebody of the current page.

Syntax

INFORMIXDIRThe INFORMIXDIR environment variable specifies the name of the directoryin which your Informix products are installed. Do not set this environmentvariable to a pathname that exceeds 64 characters.


setenv FGLSKIPNXTPG 1 FGLSKIPNXTPG=1export FGLSKIPNXTPG


INFORMIXTERM

INFORMIXTERMOn platforms that support terminfo capability, the INFORMIXTERMenvironment variable specifies whether 4GL should use the termcap orterminfo files to locate terminal capability information. If you do not setINFORMIXTERM, 4GL uses termcap.

To use terminfo, your system must fully support the UNIX System Vterminfo library interface. Not all platforms provide proper terminfosupport. To determine whether your platform supports terminfo to Informixrequirements (and therefore, whether setting INFORMIXDIR will have aneffect) use the following command:

nm $INFORMIXDIR/bin/upscol | grep tigetstr

If the command yields no output, your platform does not have terminfosupport and setting INFORMIXTERM has no effect.

If the command produces a reference line for the tigetstr function, thenyour platform supports terminfo and you can use the INFORMIXTERMenvironment variable to select terminfo functionality. Here is an exampleof a reference line:

[3810] | 1281040| 80|FUNC |GLOB |0 |9 |tigetstr


IXOLDFLDSCOPE

IXOLDFLDSCOPEThe IXOLDFLDSCOPE environment variable is recognized by 6.04 and laterreleases of 4GL. It allows programs that were written for Version 6.00 andearlier releases that have incorrect field qualifiers to avoid the field qualifierchecking mechanism that was introduced with Version 6.01.

Prior to Version 6.01, the following syntax ran successfully even if the qualifiername did not match the name of the field qualifier in the form (table name,screen record name) or the literal FORMONLY:

{BEFORE|AFTER} FIELD qualifier.fieldname

Starting with Version 6.01, the qualifiers for field names and the qualifiers onthe form must match. As a result, some 4GL programs that ran prior toVersion 6.01 now terminate with error -1129 at runtime because the qualifiernames, although stated explicitly, do not match.

ExampleIn a form:

...attributesa = FORMONLY.myfield1;...INSTRUCTIONSSCREEN RECORD f_scrn_rec (FORMONLY.myfield1 THRUFORMONLY.myfieldn)

In a 4GL program:

...DEFINE progrec RECORD ... END...INPUT progrec.* WITHOUT DEFAULTS FROM f_scrn_rec.*

AFTER FIELD FORMONLY.myfield1LET mykeyval = fgl_lastkey()

END INPUT


IXOLDFLDSCOPE

In the 4GL example, the INPUT source uses the screen record name as thequalifier, but the AFTER FIELD clause references the inherent qualifier,FORMONLY. (If the fields were based on database columns, the table namewould replace FORMONLY.) The field-matching code for CONSTRUCT andINPUT considers the proper qualifier to be the one given in the FROM clause.A mismatch results, and error -1129, Field in BEFORE/AFTER clause notfound in form, is issued.

When you encounter this error, you should correct these references.However, if doing so presents a significant barrier to upgrading, you can usea backward-compatible mechanism to disable the qualifier test, effective withthe 6.04 release.

To activate this backward-compatible (no checking) mode, you must set andexport the variable IXOLDFLDSCOPE in your environment at runtime (not atcompile time). You can set IXOLDFLDSCOPE to any non-blank value.

Including IXOLDFLDSCOPE in your calling environment disables thequalifier check. However, you lose the benefits of, for example, being able touse fields from multiple records in an INPUT statement even if a given fieldname occurs in more than one participating record.

Syntax


setenv IXOLDFLDSCOPE any-value IXOLDFLDSCOPE=any-valueexport IXOLDFLDSCOPE

any-value is any non-blank value.


LINES and COLUMNS

LINES and COLUMNSUNIX platforms support various ways to control the sizes of screens andwindows in terms of lines (or rows) and columns. Depending on the methodthat your platform uses, two environment variables, LINES and COLUMNS,might be useful in controlling the character dimensions of your screen.

One common way to control the character dimensions of screens is the use ofinput/output control (ioctl()) calls. To see if your platform uses this method,enter the command stty -a. If the system response includes explicit valuesfor rows and columns, then ioctl() control is in effect. The following exampleillustrates this:

% stty -aspeed 9600 baud;rows = 24; columns = 80;intr = ^c; quit = ^|; erase = ^h; kill = ^u;...

If your platform uses ioctl() calls to control screen dimensions, the operatingsystem or windowing facility probably provides a way to resize the screenusing the mouse or trackball.

If your platform does not use ioctl() calls to control screen dimensions, youcan use the LINES and COLUMNS environment variables to specify thescreen dimensions. On such a platform, if LINES or COLUMNS is not set, thecorresponding value is taken from the rows or columns field in the terminfoor termcap entry in use, as indicated by the TERM environment variable.


LINES and COLUMNS

Syntax

Tip: If either LINES or COLUMNS is set to an invalid value (that is, not a positiveinteger), it is ignored, and the required value is read from the termcap or terminfoentry as applicable.


setenv COLUMNS numcsetenv LINES numl

COLUMNS=numcLINES=numlexport COLUMNS LINES

numc is the integer number of columns.

numl is the integer number of lines (rows).


PROGRAM_DESIGN_DBS

PROGRAM_DESIGN_DBSThe 4GL and RDS Programmer’s Environments (i4gl and r4gl) use a databaseto store the names of the objects that are used to create programs and theirbuild dependencies. This database is a standard INFORMIX-SE orINFORMIX-OnLine database (depending on which server you are using).

The default name for this database is syspgm4gl.

In Versions 6.01 and later, both Programmer’s Environments let the userselect another name for the Programmer’s Environment database. This isparticularly useful when you are using OnLine servers because only onedatabase can be named syspgm4gl at any given time.

To choose a different name for the database for your Programmer’sEnvironment, set the environment variable PROGRAM_DESIGN_DBS to thedesired name.

Syntax

Important: The dbname value must obey the rules for database names for your server.That is, the name can contain only digits, letters, and underscores, and it can be nomore than 10 characters long (or 18 characters for OnLine servers).

For example, to use the name jane_syspg for your Programmer’sEnvironment database, set PROGRAM_DESIGN_DBS to jane_syspg in yourcalling environment before you run i4gl or r4gl.


setenv PROGRAM_DESIGN_DBS db_name PROGRAM_DESIGN_DBS=db_nameexport PROGRAM_DESIGN_DBS


SUPOUTPIPEMSG

SUPOUTPIPEMSGIn a 4GL report, you can direct the output to a pipe either by appending TOPIPE to the START REPORT statement or by including the REPORT TO PIPEclause in the OUTPUT section of the report definition. A program that furtherprocesses the output, such as a shell script or printer routine, usually receivesthe output of the report through the pipe.

In 4GL Versions 6.02 and earlier, if the program at the end of the pipe termi-nated while receiving data from the pipe, the 4GL application would exitsilently without any indication of a problem.

In 4GL Versions 6.03 and higher, when the receiving program at the readingend of the pipe dies, the next PRINT or SKIP statement will, by default, resultin error -1324, A report output file cannot be written to. This is stilla fatal error. It cannot be handled by the 4GL program by using theWHENEVER ERROR statement.

For those users who prefer the old behavior (where the 4GL program issilently terminated), you can retain that behavior using theSUPOUTPIPEMSG environment variable. If you set and exportSUPOUTPIPEMSG in the user environment at program execution time and areport output pipe dies prematurely, the 4GL program terminates withoutany error message.


8Chapter

Error Message Modifications

New and Changed Error Messages . . . . . . . . . . . . . 8-3

Deleted Error Messages . . . . . . . . . . . . . . . . . 8-16

8-2 INFO

everal error messages have been added, changed, or removed inRelease 6.0 of INFORMIX-4GL. This chapter lists the error messages numeri-cally, within the following two categories:

■ New and changed error messages

■ Deleted error messages

For a complete list of 4GL error messages, see Informix Error Messages, Version6.0. If you are using a 7.0 or greater server, look in the corresponding manual.

New and Changed Error MessagesThe following error messages were new for Release 4.1, are new for Release6.0, or were changed for Release 6.0.

-1140 NEXT OPTION is a hidden option.

The option named in this NEXT OPTION statement has previouslybeen hidden with the HIDE OPTION statement. Since it is not visibleto the user, it cannot be highlighted as the next choice.

-1168 Command does not appear in the menu.

The SHOW OPTION, HIDE OPTION, or NEXT OPTION statementcannot refer to an option (command) that does not exist. Check thespelling of the name of the option.

S

Error Message Modifications 8-3

New and Changed Error Messages

-1170 The type of your terminal is unknown to the system.

Check the setting of your TERM environment variable and thesetting of your TERMCAP or TERMINFO environment variable.Check with your system administrator if you need help with thisaction.

-1176 A COMMAND KEY value occurs elsewhere in the current menu.

In a 4GL menu, the same key value is used in more than oneCOMMAND KEY clause or is used in both a COMMAND clause and aCOMMAND KEY clause. A key value can apply to only one action ina menu. Change the COMMAND or COMMAND KEY clause so that nokey value has more than one action coded for it.

-1268 Invalid DATETIME or INTERVAL qualifier.

This statement contains a DATETIME or INTERVAL qualifier thatis not acceptable. These qualifiers may contain only the words YEAR,MONTH, DAY, HOUR, MINUTE, SECOND, FRACTION, and TO. FRAC-TION may be followed by a number from 1 to 5 in parentheses.Inspect the statement for missing punctuation and misspelledwords. It is a common error to add an s, as in MINUTES, which isincorrect.

-1328 A temporary table needed for a report could not be created in theselected database. The user must have permission to create tables inthe selected database, and there must be no existing table namedt_reportname already in the database.

Within the report function, 4GL generated an SQL statement to saverows into a temporary table. However, the temporary table could notbe created. This is probably due to a name collision, a shortage ofdisk space, or a shortage of operating-system file handles. Look forother error messages (on the system console or system log file) thatmight give more details.



-1329 A database index could not be created for a temporary database tableneeded for a report. There must be no existing index namedt_reportname already in the database.

Within the report function, 4GL generated SQL statements to saverows into a temporary table. However, an index could not be createdon the temporary table. This is probably due to a name collision, ashortage of disk space, or a shortage of operating-system file han-dles. Look for other error messages (including on the system consoleor system log file) that might give more details.

-1336 The p-code compiled from module module-name is p-code version X,which is incompatible with and cannot be executed by this 4GL-RDSp-code runner. Recompile all .4gl modules in this program with acurrent version of the p-code compiler (fglpc).

The program runner or a customized runner must be compatiblewith the p-code compiler used to compile this module. Recompile allp-code using a compatible version of fglpc.

-1345 Undefined opcode. Please recompile with a compatible version offglpc.

The p-code file for the program has become corrupted or wascompiled with an incompatible version of the p-code compiler(fglpc). Recompile the whole program and run it again. If the sameerror occurs, make sure that you are running compatible versions ofthe p-code compiler and the p-code runner. If the error recurs, noteall circumstances and contact the Informix Technical SupportDepartment.



-1371 The field fieldname does not exist in the current form.

The indicated field name has been used in the NEXT FIELD statementor passed to the pf_nxfield( ) function, but it is not defined in the cur-rent form. A common error is to confuse the tag name, which is usedin the screen layout and to the left of the equals sign in theATTRIBUTES section, with the field name, which is the column nameused to the right of the equals sign in the ATTRIBUTES section. Thelatter must be used when referring to fields.

-1372 The number entered is too large to fit in the decimal or moneyvariable.

This message is probably not returned by any current Informixproduct. If it appears, refer to the explanation of error -1226. If theerror recurs, note all circumstances and contact the Informix Techni-cal Support Department.

-1373 The field fieldname is not in the list of fields in the CONSTRUCT/INPUT statement.

The built-in function get_fldbuf( ) or field_touched( ) has been calledwith the field name fieldname. However, input from that field was notrequested in this CONSTRUCT or INPUT statement. As a result, thefunction cannot return any useful value. Review all uses of thesefunctions and compare them to the list of fields at the beginning ofthe statement.

-1374 SQL character truncation or transaction warning.

The 4GL program has WHENEVER WARNING STOP in effect, anda warning condition occurred. If a DATABASE statement is involved,the condition is that the database just opened uses a transaction log.On any other statement, the condition is that a character value fromthe database had to be truncated to fit in its destination.



-1375 SQL NULL value in aggregate or mode ANSI database warning.

The 4GL program has WHENEVER WARNING STOP in effect, anda warning condition arose. If a DATABASE statement is involved, thecondition is that the database just opened is ANSI-compliant. On anyother statement, the condition is that a null value has been used inthe computation of an aggregate value.

-1376 SQL INFORMIX-OnLine or program variable mismatch warning.

The 4GL program has WHENEVER WARNING STOP in effect, anda warning condition arose. If a DATABASE or CREATE DATABASEstatement is involved, the condition is that the database server isINFORMIX-OnLine or OnLine Dynamic Server. On any other state-ment, the condition is that a SELECT statement returned more valuesthan there were program variables to contain them.

-1377 SQL float-to-decimal conversion warning.

The 4GL program has WHENEVER WARNING STOP in effect, anda warning condition arose. The condition is that in the database thatwas just opened, the database server will use the DECIMAL data typefor FLOAT values.

-1378 SQL non-ANSI extension warning.

A database operation was performed that is not part of ANSI SQL,although the current database is ANSI-compliant. This is an informa-tional message only.



-1379 Report functions may not be called directly. Please use the OUTPUTTO REPORT statement.

A report function has been entered as a result of a CALL statement.Report functions can only be executed using the START REPORT,FINISH REPORT, and OUTPUT TO REPORT statements. Review theprogram looking for places where the report function name is calledlike a normal function and change them. If you want to use some ofthe code in the report function as a subroutine, place it in a separatesubroutine and call it from the report function and other places.

-1380 Write failed. Number rows unloaded (check ulimit or disk space).

After Number lines of output were written to the unload file, an erroroccurred trying to write the next line. Look for operating-systemmessages that might give more information. Possible causes includea full disk or a disk quota limit.

-1382 SIGXFSZ received by the process. Exceeded file size limit.

You have created a file too large for the configured limits of youroperating system, resulting in a SIGXFSZ signal. Contact your systemadministrator for corrective action.

-1383 SIGXCPU received by the process. Exceeded CPU time limit.

You have used more CPU time than the configured limits of youroperating system allow, resulting in a SIGXFSZ signal. Contact yoursystem administrator for corrective action.

-1386 This feature is not available in this release.

You have attempted to call a function with a name that has beenreserved for a future internal 4GL function. That function call is notavailable in this release.



-2014 There were an incorrect number of arguments on the operating-system command line. At least one argument is expected.

When you run the form compiler from the command line, you mustspecify either the -d option or the name of a form.

-2932 Formats may be specified only for numeric or DATE columns.

This attribute statement specifies a FORMAT string, but the data typeof the field is not one of those that support formatting: INTEGER,SMALLINT, SERIAL, FLOAT, SMALLFLOAT, DECIMAL (or MONEY),and DATE. If this is not a DISPLAYONLY (PERFORM) or FORMONLY(4GL) column, check that it has been associated with the proper col-umn and make sure that the column is defined in the database as youexpect.

-2933 The format width is larger than the allocated display width.

The length of the FORMAT string that is specified for this field isgreater than the length of the field itself as shown in the SCREEN sec-tion. Review the screen layout and revise it or the format so that theyagree.

-2934 The format width is less than the allocated display width.

The length of the FORMAT string specified for this field is less thanthe length of the field itself as shown in the SCREEN section. Reviewthe screen layout and revise it or the format so that they agree.

-4354 Aggregate functions cannot be performed with blob variables.

This statement applies an aggregate function such as SUM toa variable defined as BYTE or TEXT. Such variables are not in thedomain of the aggregate functions. Review the use of functions in thestatement and make sure that they are applied to the variables youintended.



-4363 The report cannot skip lines while in a loop within a header or trailer.

4GL needs to determine how many lines of space will be devoted tothe page header and trailer (otherwise it could not know how manydetail rows to allow on the page). It cannot predict how many timesa loop will be executed, so it has to forbid the use of SKIP statementsin loops in the PAGE HEADER, PAGE TRAILER, and FIRST PAGEHEADER sections.

-4374 This type of statement can only be used within a MENU statement.

This statement, for example a SHOW OPTION statement, only makessense within the context of a MENU statement. Review the programin this vicinity to see if an END MENU statement has been misplaced.If you intended to set up the appearance of a menu before displayingit, use a BEFORE MENU block within the scope of the MENU.

-4390 Only one BEFORE MENU clause is allowed for each MENU statement.

There may be only one BEFORE block of statements in a MENU. Makesure that the scope of your MENU statements is correctly markedwith an END MENU. Then combine all the preparation code for thismenu into a single BEFORE MENU block.

-4440 The field name1 precedes name2 in the record record-name and mustalso precede it when used with the THROUGH shorthand.

The THROUGH or THRU shorthand requires you to give the startingand ending fields as they appear in physical sequence in the record.Check the spelling of the names; if the names are as you intended,then refer to the DEFINE statement where the record was defined tosee why they are not in the sequence that you expected.



-4453 The size of the global string table has exceeded the limit of 65535.

The table holds literal strings and identifiers that are used in the mainfunction and at the global and module levels. The table also holds theidentifiers of forms, windows, and cursors. To avoid this error, movesome code that uses many literal strings into a separate module orinto a function. Alternatively, find a way to initialize character vari-ables without assigning literal strings, for example by reading theinitial values from a database or file. Reducing the number of globaland module variables will also help.

-4463 The NEXT FIELD statement can only be used within an INPUT orCONSTRUCT statement.

Something has caused 4GL to treat this NEXT FIELD statement as if itis not part of an INPUT or CONSTRUCT statement: possibly an earliererror, possibly a misplaced END INPUT/CONSTRUCT statement.Check to make sure that all the parts of the INPUT or CONSTRUCTstatement are properly delimited.

-4485 Only blob variables of type BYTE or TEXT may be used in a LOCATEstatement.

The LOCATE statement is used to assign a BYTE or TEXT variable toa medium, either memory or a file. This is supported only for thesedata types; all other types of variables are located in memory.

-4486 Blob variables and wordwrap fields cannot be printed in reportheaders or trailers.

4GL has to be able to predict how many lines will be used up ina report header or trailer. Since the size of a TEXT variable and thenumber of lines in a WORDWRAP field are unpredictable, you cannotdisplay one in these contexts.



-4487 Cannot mix report parameters and local record(s) containing BLOBs.

It is not possible to mix parameter and local record definitions wherethe record contains variables of type TEXT or BYTE. Make a seconddefinition for the local record variable.

-4488 The program cannot CONTINUE or EXIT statement-name at this pointbecause it is not immediately within statement-name.

The program is attempting to CONTINUE or EXIT an INPUT orCONSTRUCT statement while a different 4GL input or output state-ment is active. For example, the EXIT INPUT statement in the follow-ing program segment is illegal, since the CONSTRUCT statement isactive:

INPUT .....CONSTRUCT ..

...EXIT INPUT...

END CONSTRUCT...

-4489 A variable used in the above statement must be a global variable.

This statement cannot refer to an argument of the function nor toa variable defined in the function. It may use only variables definedat the module level (before the MAIN section) or in the GLOBALS sec-tion. In the case of OUTPUT REPORT TO, the statement takes effectduring the execution of a START REPORT statement. At this time noarguments are passed into the report function, and no report func-tion statements are executed that could initialize a local variable.Change the statement to refer to a variable that can be initializedbefore the report is started.

-4490 You cannot have multiple BEFORE clauses for the same field.

You have multiple BEFORE FIELD clauses that reference the samefield. Only one is allowed. Combine all code that you want executedupon entry into that field into one BEFORE FIELD block.



-4491 You cannot have multiple AFTER clauses for the same field.

You have multiple AFTER FIELD clauses that reference the same field.Only one is allowed. Combine all code that you want executed uponentry into that field into one AFTER FIELD block.

-4492 This type of statement cannot be used in a report.

You have attempted to use a screen-interaction statement (forexample, CONSTRUCT, DISPLAY ARRAY, INPUT [ARRAY], MENU,PROMPT) or a RETURN statement from within a report. This is notallowed.

-4520 Old UNLOAD pcode detected.

The p-code compiled from the module name above uses an older,incompatible implementation of the UNLOAD statement. Recompileall .4gl modules in this program with a current version of the p-codecompiler (fglpc).

-4525 Global variable name cannot be found in the descriptor table.

If you deleted or modified a global variable in the globals file, be sureto recompile all the modules that use the global variable. If this doesnot solve the problem, contact Informix Technical Support.

-4535 The format string in the USING clause is null or has not beeninitialized.

A character string used in a USING clause has an invalid or NULLvalue. Assign an appropriate value to the string and recompile theprogram.



-4652 The function function-name can only be used within an INPUT orCONSTRUCT statement.

Check that you have not attempted to use the get_fldbuf( ) functionor the field_touched( ) function with a statement other than INPUT,INPUT ARRAY, or CONSTRUCT.

-4653 No more than one BEFORE or AFTER INPUT or CONSTRUCT clausecan appear in an INPUT or CONSTRUCT statement.

There can be only one BEFORE block of statements in each of thesestatement types. Make sure that the scope of all your INPUT andCONSTRUCT statements is correctly marked with END INPUT or ENDCONSTRUCT. Then combine all the preparation code into a singleBEFORE block for each one.

-4655 Invalid range specified for VARCHAR.

A VARCHAR variable definition improperly requests a reserve-sizelarger than its maximum size or requests a negative reserve-size.

-4705 More than one Runner record found for this program.

Your program design database has more than Runner record withthe desired name. If this error occurs more than once, drop your pro-gram design database and rebuild it.

-4706 More than one instance of table table-name found in program designdatabase.

Your program design database has more than one table with thedesired name. It was somehow improperly converted to MODEANSI, or it is corrupted. If this error occurs more than once, dropyour program design database and rebuild it.



-4707 Only part of the program design database was found.

Your program design database is missing one or more tables. If thiserror occurs more than once, drop your program design databaseand rebuild it.

-4708 Too many programs found. Try again.

An internal error occurred in looking up defined programs. Retryyour task. If the error repeats, exit the Programmer's Environmentand try again. If it persists, drop your program design database andrebuild it.

-10099 Invalid delimiter. Do not use '\' or hex digits (0-9, A-F, a-f).

Change the delimiter character that the UNLOAD file uses.


Deleted Error Messages

Deleted Error MessagesThe error messages in this list will no longer appear when you work with4GL.

-2800 The first line of the specification must be the keyword databasefollowed by the database name, or the FORMONLY keyword (4GLonly). An optional WITHOUT NULL INPUT may also follow.

Aside from comment lines, a form specification must begin bynaming a database. Review the file for punctuation and spellingerrors. Refer to the reference manual for this product for the optionsthat are allowed in the DATABASE statement. (This message is notcurrently used. It might be encountered with products of Version 4.0or earlier.)

-4394 The MENU statement has two or more selections using the key-namename.

This restriction no longer exists.

-4444 Too many colors specified for window.

You can include only one color in the ATTRIBUTES clause of the OPENWINDOW statement. It specifies the foreground (text) color for thewindow. Once the window is open you can display text in other col-ors through the attributes in a form, or the ATTRIBUTES clause of aDISPLAY, INPUT, or CONSTRUCT statement.


@

Index

O QCA B D E F G H I J K L M N P R S T U V W X Y Z

Index

A-a option 7-4AFTER CONSTRUCT clause,

CONSTRUCT statement 3-4,6-20

AFTER DELETE clause, INPUTARRAY statement 6-80

AFTER FIELD clauseCONSTRUCT statement 6-22INPUT ARRAY statement 6-81INPUT statement 6-57, 6-59

AFTER INPUT clauseINPUT ARRAY statement 6-78,

6-86INPUT statement 6-55, 6-59

AFTER INSERT clause, INPUTARRAY statement 6-79

AFTER ROW clause, INPUTARRAY statement 6-79

Alias of a table, in a formspecification file 6-15, 6-17

ANSI C compiler 4-13ANSI compliance 3-29-ansi flag 3-20, 3-29, 7-4-anyerr flag 3-30, 3-26, 4-4, 7-4AnyError Error Scope 3-26, 3-30,

4-5, 7-6Asterisk (*) notation

for all columns, all fields 6-16wildcard 6-30

ATTRIBUTE clauseCONSTRUCT statement 6-10,

6-17INPUT ARRAY statement 6-74INPUT statement 6-52

AUTONEXT attribute,CONSTRUCT statement 6-27

BBackward compatibility, using shell

scripts 4-7BEFORE CONSTRUCT clause,


BEFORE DELETE clause, INPUTARRAY statement 6-78

BEFORE FIELD clauseCONSTRUCT statement 6-21INPUT ARRAY statement 6-80INPUT statement 6-56

BEFORE INPUT clauseINPUT ARRAY statement 6-76INPUT statement 6-55

BEFORE INSERT clauseINPUT ARRAY statement 6-77screen array 6-77

BEFORE MENU clause, MENUstatement 6-102

BEFORE ROW clause, INPUTARRAY statement 6-77

BEGIN WORK statement 6-95BLACK attribute 3-13Built-in function 5-3BY NAME keyword

CONSTRUCT statement 6-14INPUT statement 6-50using 6-14

O QCA B D E F G H I J K L M N P R S T U V W X Y Z @

CC code 4-7C compiler 4-7C shell variants 4-18C4GL script

changes to compilationsystem 4-5

help message 4-15to do compilations 4-8

C4GLFLAGS environmentvariable 3-26, 4-4, 4-8, 4-12, 7-4

C4GLNOPARAMCHKenvironment variable 4-4, 7-5

CASE statementenhancements 2-3syntax and notes 6-6

CC environment variable 4-5, 4-11CLIPPED operator 3-39Closed cursor, closing 3-19Colon ( : ) symbol

delimiter in DATETIMEvalues 6-30

delimiter in INTERVALvalues 6-30

ranges with CONSTRUCT 6-30COMMAND clause, MENU

statement 6-102COMMIT statement 6-94, 6-95COMMIT WORK statement 6-95CONSTRUCT statement

AFTER FIELD clause 3-4BEFORE FIELD clause 3-4enhancements 2-4, 3-4NEXT FIELD statement 3-4ON KEY clause 3-4syntax and notes 6-9using functions in 6-33wildcard characters 6-30

CONTINUE CONSTRUCTstatement 2-4, 3-4, 6-26

CONTINUE INPUT statementINPUT ARRAY statement 6-85with INPUT 6-60

CONTINUE MENUstatement 6-103

Cursorclosing 3-19movement in a form 3-8

Cursor movementas determined by

CONSTRUCT 6-32as determined by INPUT 6-59,

6-64as determined by INPUT

ARRAY 6-90in a menu 6-101

CURSOR_NAME( ) function 5-5custom runner 4-15

DDatabase

making 4GL work with server 1-5unlogged 6-94upgrading 1-6

DATETIME data type 3-21DBANSIWARN environment

variable 3-20, 3-29DBESCWT environment

variable 7-7Debuggers, of source code 4-13Display field, specifying search

criteria 6-10Dynamically linked (shared library)

program 4-16

EEight-Column Limit, ORDER BY

clause 3-25Embedded language 1-4, 1-5END CONSTRUCT statement 6-27END INPUT statement

INPUT ARRAY statement 6-86with INPUT 6-61

END MENU statement 6-106Enhanced statements 2-3Environment changes, new

server 1-5Environment variables

affect on 4GL compiler 4-3C4GLFLAGS 3-26, 4-4, 4-8, 4-12,

7-4C4GLNOPARAMCHK 4-4, 7-5CC 4-5, 4-11DBANSIWARN 3-20, 3-29

DBESCWT 7-7FGLPCFLAGS 4-4, 7-4FGLSKIPNXTPG 7-8INFORMIXC 4-5, 4-11INFORMIXDIR 7-8INFORMIXTERM 7-9IXOLDFLDSCOPE 7-10new 2-6PROGRAM_DESIGN_DBS 2-7,

7-14SQLEXEC 1-6SUPOUTPIPEMSG 7-15

Error messages 1-4, 2-7, 8-3deleted 8-16new and changed 8-3

Error Scope, defined 3-26Errors and inconsistencies 3-27EXIT CONSTRUCT statement 3-4,

6-27EXIT INPUT statement

INPUT ARRAY statement 6-86INPUT statement 6-61

EXIT MENU statement 6-99, 6-104

Ffglc compiler 4-7fglc2 compiler 4-7fglc3 compiler 4-7fglgo runner 4-15fglpc compiler 5-5FGLPCFLAGS environment

variable 4-4, 7-4FGLSKIPNXTPG environment

variable 7-8fgl_keyval( ) function 3-11fgl_lastkey( ) function 3-11, 6-12,

6-89Fields

initial values to display 3-9left-justification 3-42

field_touched( ) function 3-12, 6-12,6-25

Form fields, left-justification 3-42FORM MODE 3-454GL shared library

implementation 4-16



4GL error handling, changesto 3-30

4GL operators, precedence andassociativity 3-39

4GL runtime errors, handling 3-25FROM clause



Gget_fldbuf( ) function 3-10, 6-12,

6-18, 6-25, 6-89Global variable

name conflicts 5-7usage guidelines 3-24

GLOBALS statement,enhancements 2-5

-globcurs option 4-5, 4-10Greater-than symbol ( > ), relational

operator 6-30

HHELP clause


INPUT ARRAY statement 6-74INPUT statement 6-47, 6-54MENU statement 6-99

Help file, calling helpmessages 6-99, 6-103

Help message, displaying 6-47HIDE OPTION statement, MENU

statement 6-105

II4GL

changes to compilationsystem 4-5

cursor name hashing scheme 4-11five-phase compilation

process 4-6header files 4-12

in C4GLNOPARAMCHK 4-4libraries 4-12old behavior 4-10

i4glc1 compiler 4-6, 4-8, 4-12, 4-14,5-5

i4glc2 compiler 4-6, 4-8, 4-12, 4-14i4glc3 compiler 4-6, 4-12, 4-14i4glc4 compiler 4-7, 4-8, 4-12, 4-14i4glc4 program 4-13i4gldemo program 4-16ICB statements, nested and

recursive 3-30infield( ) function 6-89INFORMIX Relay Module 1-6INFORMIXC environment

variable 4-5, 4-11INFORMIXDIR environment

variable 7-8INFORMIX-NET 1-6INFORMIX-OnLine Dynamic

Server 1-3, 1-4, 1-5INFORMIX-SE 1-3, 1-4, 1-5INFORMIX-SQL 1-5INFORMIXTERM environment

variable 7-9Inode number

4GL stack 5-5of 4GL source file 4-10

INPUT ARRAY statementcompleting 6-91editing during 6-91syntax and notes 6-68using functions in 6-88

INPUT statementcompleting 6-65syntax and notes 6-46

Installation recommendations 1-3INTERVAL data type 3-21int_flag variable 6-23, 6-66INVISIBLE attribute 3-13Invisible options of menus 6-102ioctl( ) call 7-12ISQL 1-3, 1-5IXOLDFLDSCOPE environment

variable 7-10

K-keep option 4-5, 4-9Key

arrow keys 6-59Interrupt 6-103scrolling and editing 6-65

KEY clause, MENU statement 6-99,6-103

Keystroke, determining last 3-11

LLess-than symbol ( < ), relational

operator 6-30Libraries, shared 4-15Library calls 3-27LINE MODE 3-45-linenos option 4-13LOAD statement

enhancements 2-5transaction management 6-94

MMAKE 4-11MENU statement

COMMAND KEY conflict 6-111,6-112

creating menus 3-7Details option 3-7Exit option 3-7help messages 6-103keys in a command key

clause 6-111Long_menu option 3-7Query option 3-7Short_menu option 3-7syntax and notes 6-98using variables in 6-108

Menu-building utility 6-98Menu, programmer-defined

creating 6-98displaying options 6-101naming menu options 6-102requesting help from 6-103selecting options 6-101

mkmessage utility 6-74

Index 3

@O QCA B D E F G H I J K L M N P R S T U V W X Y Z

MODE ANSI 6-95, 6-96, 6-97Multipass report 3-24myutil object 4-17

NNested and recursive operations

early exits 3-35notes about 3-39

NewEra 1-4, 1-5NEXT FIELD statement

CONSTRUCT statement 6-24INPUT ARRAY statement 6-84INPUT statement 6-59

NEXT OPTION statement 6-104NLS database, using with

I4GL 4-13-nokeep option 4-5, 4-9-nolinenos option 4-13non-MODE ANSI 6-96Normal Error Scope 3-26, 3-28, 3-30NULL character, in report 3-22Numeric form fields, left-

justification 3-42

OON clause, CONSTRUCT

statement 6-15ON KEY clause



ON keyword, CONSTRUCTstatement 6-10

OnLine Dynamic Server 1-4, 1-5Operator range 6-30OPTION functionality 3-44OPTIONS statement, PROMPT

LINE default behavior 6-113ORDER BY clause 3-25ORD( ) function 5-4

PP-code 3-30Period ( . ) symbol, range

operator 6-30-phase option 4-5, 4-8Pipe 7-15popstring( ) function 3-46Product directory 1-4Program features, menus 6-98Programmer's Environment 7-14PROGRAM_DESIGN_DBS

environment variable 2-7, 7-14PROMPT statement

display list 6-113enhancements 2-6

QQuery by example

CONSTRUCT statement 6-37managing 3-4using the range operator 6-30using wildcard characters 6-30

Question mark ( ? ), wildcard 6-30quit_flag variable 6-66, 6-92

RRange of values, query by

example 6-30Rapid Development System

(RDS) 3-25, 4-4, 4-10, 4-11, 7-5RDS. See Rapid Development

SystemRelay Module 1-6Remote databases, support of 3-21Report

input statements 3-25multipass 3-24parameterless 3-23printing a NULL character 3-22temporary tables created by

multipass 3-24REPORT statement

functionality 3-42used with WORDWRAP 3-41

Report writingenhancements 3-22guidelines 3-22

Reserved words 3-20Response time, poor 7-7retstring( ) function 3-46RETURN statement, using in a

report 3-23Ring menu 6-102ROLLBACK statement 6-95ROLLBACK WORK statement 6-95Rows, inserting and deleting in

INPUT ARRAY statement 6-90RUN functionality 3-44Runtime errors, handling 3-25RUN...RETURNING clause 3-45

SScreen array 6-10Screen field buffers, manipulating

values 3-10Screen input 3-6Screen interactions 3-3Screen record 6-10SE 1-3, 1-4, 1-5Search criteria, specifying 6-28Segmented form fields, using with

WORDWRAP 3-40SELECT DISTINCT, UNION

ALL 3-16SELECT UNIQUE, UNION

ALL 3-16Sequence of characters sent by

function and arrow keys 7-7Server, environment changes 1-5-shared option 4-4, 4-16, 7-4-shared parameter 4-16-shared flag 4-17Shared library

comparison 4-15implementation 4-16using 4-16

Shell scripts for backwardcompatibility 4-7

SHOW OPTION statementwith MENU 6-105



SKIP TO TOP OF PAGE 7-8command 7-8

Source code debuggers 4-13Spacebar 6-101SQLEXEC environment

variable 1-6sqlrm file 1-6START REPORT statement 7-15Statements

BEGIN WORK 6-95COMMIT 6-94enhanced 2-3ROLLBACK 6-95

STATUS variable 3-27stty option 3-45SUPOUTPIPEMSG environment

variable 7-15syscolval table 6-73syspgm4gl database 7-14

TTable

alias for table name 6-15, 6-17querying 3-14

termcap file 6-19, 6-76rows or columns 7-12terminal capability 7-9

terminfo file 6-19, 6-76rows or columns 7-12terminal capability 7-9

TO PIPE clause 7-15

UUNION ALL clause 3-15UNION ALL statement

SELECT DISTINCT 3-16SELECT UNIQUE 3-16

UNION operator, between SELECTstatements 3-15

UNIX 6-83UNLOAD statement

enhancements 2-6, 6-115Unlogged database 6-94Upgrading database 1-6Upgrading to 4GL 6.0 1-3upscol utility 3-21

VVARCHAR data type 3-21Variable

as identifier 3-17in global scope 5-7

WWHERE clause

pattern matching in 6-30ranges in 6-30search conditions 6-30

Wildcard character 6-30Window, displaying a menu 6-100WITHOUT DEFAULTS clause


WORDWRAP statementCOMPRESS 6-61in REPORTS 3-41INPUT statement 6-61NONCOMPRESS 6-61using with segmented form

fields 3-40

Z-z option 4-4, 4-5, 4-9, 7-4Zero or more characters, symbol

for 6-30

Index 5

@O QCA B D E F G H I J K L M N P R S T U V W X Y Z


reference manual supplement - pacs support · reference manual supplement version 6.0 september...

Documents