INFORMIX-4GL

SQL-Based Application Development Language for the UNIX Operating System

Reference Manual

INFORMIX-4GL

Version4.0 March 1990 Part No. 000-7044

THE INFORMIX SOFTWARE AND USER MANUAL ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE INFORMIX SOFTWARE AND USER MANUAL IS WITH YOU. SHOULD THE INFORMIX SOFTWARE AND USER MANUAL PROVE DEFECTIVE, YOU (AND NOT INFORMIX OR ANY AUTHORIZED REPRESENTATIVE OF INFORMIX) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT WILL INFORMIX BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF OR INABILITY TO USE SUCH INFORMIX SOFTWARE OR USER MANUAL, EVEN IF INFORMIX OR AN AUTHORIZED REPRESENTATIVE OF INFORMIX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. IN ADDITION, INFORMIX SHALL NOT BE LIABLE FOR ANY CLAIM ARISING OUT OF THE USE OF OR INABILITY TO USE SUCH INFORMIX SOFTWARE OR USER MANUAL BASED UPON STRICT LIABILITY OR INFORMIXS NEGLIGENCE. SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS AND YOU MAY ALSO HAVE OTHER RIGHTS, WHICH VARY FROM STATE TO STATE. All rights reserved. No part of this work covered by the copyright hereon may be reproduced or used in any form or by any meansgraphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systemswithout permission of the publisher. Published by: Informix Software, Inc. 4100 Bohannon Drive Menlo Park, CA 94025
INFORMIX and C-ISAM are registered trademarks of Informix Software, Inc. UNIX is a trademark of AT&T. IBM is a registered trademark of the International Business Machines Corporation.

RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subdivision (b)(3)(ii) of the Rights in Technical Data and Computer Software Clause at 52.227-7013 (and any other applicable license provisions set forth in the Government contract).
Copyright 1981-1990 by Informix Software, Inc. +

ii

Table of Contents

INFORMIX-4GL
Reference Manual
Introduction
About This Manual Intro-3 Related Informix Products and Documentation Database Management Systems Intro-5 Process Architecture Intro-5 Informix Database Engines Intro-6 Summary of Chapters Intro-8 Syntax Conventions Intro-9 The Demonstration Database Intro-11 Chapter 1 Intro-4

Compiling 4GL Source Files Chapter Overview 1-5 The Two Implementations of INFORMIX-4GL 1-5 INFORMIX-4GL (C Compiler Version) 1-7 The Programmers Environment (C Compiler Version) 1-7 The INFORMIX-4GL Menu 1-8 The MODULE Design Menu 1-9 The FORM Design Menu 1-14 The PROGRAM Design Menu 1-18 The QUERY LANGUAGE Menu 1-25 Creating Executable 4GL Programs (C Compiler Version) 1-25 Working in the Programmers Environment 1-25 Working at the Command Line 1-30 Program Filename Extensions (C Compiler Version) 1-35 INFORMIX-4GL (Rapid Development System) 1-36 The RDS Programmers Environment 1-36 The INFORMIX-4GL Menu 1-37 The MODULE Design Menu 1-38 The FORM Design Menu 1-43

The PROGRAM Design Menu 1-48 The QUERY LANGUAGE Menu 1-54 Creating Executable RDS Programs 1-54 Working in the RDS Programmers Environment Working at the RDS Command Line 1-59 RDS Program Filename Extensions 1-72 Chapter 2 INFORMIX-4GL Programming Chapter Overview 2-3 Language Conventions 2-3 Comments 2-3 INFORMIX-4GL Identiers 2-4 Scope of Identiers 2-4 Constants 2-5 Program Variables 2-6 Data Types 2-7 Data Conversion 2-10 Operators and Expressions 2-11 Binding to Database and Forms 2-14 The THRU Keyword and the .* Notation INFORMIX-4GL Statements 2-16 Variable Denition 2-17 Assignment 2-17 Program Organization 2-17 Program Flow 2-18 Screen Interaction 2-19 Report Generation 2-21 Error and Exception Handling 2-21 Data Validation 2-23 Built-in Functions 2-24 ASCII 2-25 CLIPPED 2-27 COLUMN 2-29 CURRENT 2-30 DATE 2-32 DATE( ) 2-33 DAY( ) 2-34 EXTEND( ) 2-35 LENGTH( ) 2-38 MDY( ) 2-39 MONTH( ) 2-40 TIME 2-41 TODAY 2-42

1-54

2-15

iv Table of Contents

UNITS 2-43 USING 2-44 WEEKDAY( ) 2-53 YEAR( ) 2-54 C Functions 2-55 Chapter 3 Using SQL Chapter Overview 3-5 Relational Databases 3-5 SQL Identiers 3-6 Owner Naming 3-7 Database Data Types 3-8 SQL Statement Summary 3-10 Data Denition 3-11 Data Manipulation 3-12 Cursor Management 3-13 SELECT Cursors 3-13 INSERT Cursors 3-25 Dynamic Management 3-28 Preparing Statements 3-29 Executing PREPAREd Statements 3-33 Preparing Multiple SQL Statements 3-38 The FREE Statement 3-39 Data Access 3-40 User Status and Privileges 3-41 Data Integrity 3-42 Transactions 3-42 Transaction Log File Maintenance 3-45 Audit Trails 3-45 Comparison of Transactions and Audit Trails Locking 3-47 Row-Level Locking 3-48 Table-Level Locking 3-49 Wait for Locked Row 3-50 Indexing Strategy 3-50 Query Optimizer 3-52 Auto-Indexing 3-52 Clustered Indexes 3-52 NULL Values 3-53 Default Values 3-54 The NULL in Expressions 3-54 The NULL in Boolean Expressions 3-55 The NULL in WHERE Clauses 3-55

3-47

Table of Contents

The NULL in ORDER BY Clauses 3-56 The NULL in GROUP BY Clauses 3-56 The NULL Keyword in INSERT and UPDATE Statements Views 3-57 Creating and Deleting Views 3-58 Querying Through Views 3-58 Modifying Through Views 3-59 Privileges with Views 3-60 Data Constraints Using Views 3-60 Outer Joins 3-61 Table Access by ROWID 3-62 SQLCA Record 3-63 TODAY, CURRENT, and USER Functions 3-65 Chapter 4 Form Building and Compiling Chapter Overview 4-3 Structure of a Form Specication File 4-4 DATABASE Section 4-7 SCREEN Section 4-9 TABLES Section 4-15 ATTRIBUTES Section 4-17 AUTONEXT 4-24 COLOR 4-26 COMMENTS 4-28 DEFAULT 4-30 DISPLAY LIKE 4-32 DOWNSHIFT 4-33 FORMAT 4-34 INCLUDE 4-36 NOENTRY 4-38 PICTURE 4-39 REQUIRED 4-41 REVERSE 4-43 UPSHIFT 4-44 VALIDATE LIKE 4-46 VERIFY 4-47 WORDWRAP 4-48 INSTRUCTIONS Section 4-52 Default Screen Attributes 4-57 The upscol Tables in a MODE ANSI Database 4-60 Creating and Compiling a Form 4-61 Through the Programmers Environment 4-62 Through the Operating System 4-63 Using PERFORM Forms in INFORMIX-4GL 4-64

3-57

vi Table of Contents

Chapter 5

Report Writing Chapter Overview 5-3 Calling a REPORT Routine 5-4 Structure of a REPORT Routine 5-5 DEFINE Section 5-7 OUTPUT Section 5-9 REPORT TO 5-10 LEFT MARGIN 5-12 RIGHT MARGIN 5-13 TOP MARGIN 5-15 BOTTOM MARGIN 5-16 PAGE LENGTH 5-17 ORDER BY Section 5-18 FORMAT Section 5-20 EVERY ROW 5-21 Control Blocks 5-23 AFTER GROUP OF 5-25 BEFORE GROUP OF 5-27 FIRST PAGE HEADER 5-29 ON EVERY ROW 5-31 ON LAST ROW 5-33 PAGE HEADER 5-34 PAGE TRAILER 5-36 Statements 5-37 NEED 5-38 PAUSE 5-39 PRINT 5-40 PRINT FILE 5-42 SKIP 5-43 Expressions and Built-in Functions Aggregates 5-46 LINENO 5-48 PAGENO 5-49 SPACES 5-50 WORDWRAP 5-51 4GL Function Library Chapter Overview 6-3 The 4GL Library Functions ARG_VAL 6-4 ARR_COUNT 6-6 ARR_CURR 6-7 DOWNSHIFT 6-9

5-44

Chapter 6

6-3

Table of Contents vii

ERR_GET 6-10 ERR_PRINT 6-11 ERR_QUIT 6-12 ERRORLOG 6-13 INFIELD 6-14 LENGTH 6-16 NUM_ARGS 6-17 SCR_LINE 6-18 SET_COUNT 6-20 SHOWHELP 6-21 STARTLOG 6-23 UPSHIFT 6-25 Chapter 7 INFORMIX-4GL Statement Syntax Types of Statements 7-5 Statements Supported Only on INFORMIX-SE 7-6 Statements Supporting INFORMIX-OnLine Enhancements INFORMIX-4GL Extensions to ANSI Syntax 7-7 Denition of Statements 7-11 ALTER INDEX 7-12 ALTER TABLE ( O ) 7-14 BEGIN WORK 7-18 CALL 7-19 CASE 7-21 CLEAR 7-23 CLOSE 7-25 CLOSE DATABASE 7-27 CLOSE FORM 7-28 CLOSE WINDOW 7-30 COMMIT WORK 7-31 CONSTRUCT 7-32 CONTINUE 7-38 CREATE AUDIT 7-39 CREATE DATABASE ( O ) 7-41 CREATE INDEX 7-44 CREATE SYNONYM 7-47 CREATE TABLE ( O ) 7-49 CREATE VIEW 7-57 CURRENT WINDOW 7-60 DATABASE 7-62 DECLARE 7-64 DEFER 7-69 DEFINE 7-71

7-7

viii

Table of Contents

DELETE 7-73 DISPLAY 7-75 DISPLAY ARRAY 7-79 DISPLAY FORM 7-83 DROP AUDIT 7-85 DROP DATABASE 7-86 DROP INDEX 7-88 DROP SYNONYM 7-89 DROP TABLE 7-90 DROP VIEW 7-91 ERROR 7-92 EXECUTE 7-94 EXIT 7-96 FETCH 7-98 FINISH REPORT 7-101 FLUSH 7-102 FOR 7-104 FOREACH 7-106 FREE ( O ) 7-109 FUNCTION 7-110 GLOBALS 7-112 GOTO 7-114 GRANT 7-115 IF 7-118 INITIALIZE 7-120 INPUT 7-122 INPUT ARRAY 7-129 INSERT 7-138 LABEL 7-141 LET 7-142 LOAD 7-143 LOCK TABLE 7-146 MAIN 7-148 MENU 7-149 MESSAGE 7-154 OPEN 7-156 OPEN FORM 7-159 OPEN WINDOW 7-160 OPTIONS 7-165 OUTPUT TO REPORT 7-170 PREPARE 7-171 PROMPT 7-173 PUT 7-177
Table of Contents ix

RECOVER TABLE 7-179 RENAME COLUMN 7-181 RENAME TABLE 7-182 REPORT 7-184 RETURN 7-186 REVOKE 7-187 ROLLBACK WORK 7-189 ROLLFORWARD DATABASE 7-190 RUN 7-191 SCROLL 7-192 SELECT 7-193 SET EXPLAIN 7-194 SET LOCK MODE ( O ) 7-197 SLEEP 7-199 START DATABASE 7-200 START REPORT 7-202 UNLOAD 7-203 UNLOCK TABLE 7-205 UPDATE 7-206 UPDATE STATISTICS 7-210 VALIDATE 7-211 WHENEVER 7-213 WHILE 7-216 The SELECT Statement 7-218 SELECT Clause 7-222 INTO Clause 7-224 FROM Clause 7-226 WHERE Clause 7-228 GROUP BY Clause 7-240 HAVING Clause 7-242 ORDER BY Clause 7-243 INTO TEMP Clause 7-245 UNION Operator 7-246 Functions in SQL Statements 7-248 Aggregate Functions 7-249 LENGTH( ) 7-251 DATE( ) 7-252 DAY( ) 7-253 MDY( ) 7-254 MONTH( ) 7-255 WEEKDAY( ) 7-256 YEAR( ) 7-257 CURRENT 7-258 EXTEND( ) 7-260
x Table of Contents

Appendix A Appendix B Appendix C Appendix D Appendix E Appendix F Appendix G Appendix H Appendix I Appendix J

Demonstration Database and Application System Catalogs Environment Variables Reserved Words INFORMIX-4GL Utility Programs DECIMAL Functions for C Outer Joins ASCII Character Set Modifying termcap and terminfo Working with DATETIME and INTERVAL Data Error Messages Index

Table of Contents xi

xii

Table of Contents

Introduction

Introduction
About This Manual 3 4 Related Informix Products and Documentation Database Management Systems Process Architecture 5 Informix Database Engines Summary of Chapters Syntax Conventions 9 11 8 6 5

The Demonstration Database

Introduction

About This Manual

Informix Software, Inc. developed INFORMIX-4GL (Fourth-Generation Application Development Language) for the database designer who wants to create custom database management applications. You can use INFORMIX-4GL to perform the following functions:

Embed industry-standard database creation and query statements (SQL)

in a fourth-generation language (INFORMIX-4GL).

Create interactive screen forms that provide an interface between the user
of your application and the database.

Design output reports to list and summarize database information.

The INFORMIX-4GL language is available in two versions, both of which support a similar user interface:

The C Compiler Version, based on compiled C code, is intended primarily

for a production environment.

The Rapid Development System compiles source les into p-code

(pseudo-code) to reduce application development time. Chapter 1 identies the differences between these two implementations, which mostly involve details of processing INFORMIX-4GL source les. Documentation for INFORMIX-4GL includes this and one other volume. An introductory book, the INFORMIX-4GL User Guide, presents both SQL and INFORMIX-4GL in stages, through example 4GL programs that increase in sophistication and subtlety. This book, the INFORMIX-4GL Reference Manual, describes all the syntax, rules, and denitions of the variables, statements, and keywords. Another section of this Introduction summarizes each chapter and appendix of the Reference Manual. Besides these manuals, the INFORMIX-4GL Quick Reference Guide lists the data types, operations, functions, and syntax of INFORMIX-4GL.

Introduction

Related Informix Products and Documentation

Related Informix Products and Documentation

This manual assumes that you have used INFORMIX-4GL and are familiar with the structure of relational databases. Readers with programming experience using INFORMIX-SQL or INFORMIX-ESQL/C will recognize old friends in a new setting. You can read about INFORMIX-SQL in the INFORMIX-SQL Reference Manual, and about INFORMIX-ESQL/C in the INFORMIX-ESQL/C Programmers Manual. The INFORMIX-4GL Interactive Debugger is a separate product designed for use with the INFORMIX-4GL Rapid Development System. This sourcelanguage debugger is useful when you are developing or modifying 4GL programs, or analyzing a 4GL program that someone else has written. The INFORMIX-4GL Interactive Debugger is described in the Guide to the INFORMIX-4GL Interactive Debugger. Like the INFORMIX-4GL Rapid Development System, the Debugger does not require a C-compiler, unless your application calls INFORMIX-ESQL/C functions or programmer-dened C functions. The underlying le and indexing structure of the database tables created through INFORMIX-4GL, INFORMIX-SQL, or INFORMIX-ESQL/C is built on C-ISAM. For more information about this indexed sequential access method, see the C-ISAM Programmers Manual. See also the section Related Reading in the Preface to the INFORMIX-4GL User Guide for a selected bibliography on programming in fourth-generation languages like INFORMIX-4GL. You can use INFORMIX-4GL with the INFORMIX-OnLine database engine, which supports enhanced system performance through the use of direct memory access (DMA) and raw le systems. Use of the INFORMIX-OnLine database engine with INFORMIX-4GL and other SQL products is described in the INFORMIX-OnLine Programmers Manual. The section Informix Database Engines, later in this Introduction, identies additional INFORMIX-4GL features that are available only with INFORMIX-OnLine. Note: Two les supplement the information in the manual. RELNOTES describes performance differences from earlier versions of Informix products and how these differences may affect existing applications. DOCNOTES describes feature and performance topics not covered in the manual or modied since publication. Please examine these les as they contain vital information about application and performance issues. RELNOTES and DOCNOTES are located in the $INFORMIXDIR/release directory.

Introduction

Database Management Systems

Database Management Systems

A Database Management System (DBMS) can be divided into two parts as follows:

A data language, which is the user interface to the DBMS A database engine, which takes the data denition and data manipulation
language requests and performs the requested operations Database users instruct database management systems to perform queries and other operations on a database using language the DBMS understands. There are two such languages, data denition and manipulation languages, because the user must dene the contents of a database and manipulate the data. These languages are often called, simply, data languages. The DBMS must understand these languages and translate the user instructions into appropriate instructions for the operating system and hardware. As a result of user instructions, the DBMS requests services such as allocation of space, storage and retrieval of blocks of data, and much more. The database engine operates as a process, an executing program. Database engines serve other processes, which are database applications. These applications contain the language statements that the database engine executes. Informix products use a database denition and manipulation language that is an extension of the ANSI standard SQL to send instructions to the database engine.

Process Architecture
A database engine performs SQL operations. The database engine is a process that handles storage and retrieval of data and other DBMS functions. The following gure shows this implementation for products on INFORMIX-SE.
MULTIPLE PROCESSES

INFORMIX-4GL

Pipes

INFORMIX-SE INFORMIX-SE INFORMIX-SE INFORMIX-ESQL

In Host Language

Fi Acc le ess

INFORMIX-SQL

Data

C-ISAM

Introduction

Informix Database Engines

Processes that use the database engine are implemented as applications in the following ways:

With an embedded language, such as INFORMIX-ESQL/C or INFORMIX-ESQL/COBOL

With a fourth-generation language, such as INFORMIX-4GL As part of an interactive retrieval system, such as INFORMIX-SQL
INFORMIX-SE uses C-ISAM to store and retrieve data from the disk.

A database application spawns at least two processes: the database engine process and the application process. While the database engine is often thought of as a single entity, it is actually made up of one process for each application process. This one-to-one relationship between application and database process allows the engine to respond immediately to a specic application, rather than queuing requests from all applications that need service. The database engine and application communicate using pipes.

Informix Database Engines

You can use INFORMIX-4GL or any Informix application development tool with either of two database engines: INFORMIX-SE or INFORMIX-OnLine.
INFORMIX-SE is based on C-ISAM, a library of C language calls that works with UNIX to create and manipulate database les. INFORMIX-SE works

automatically and transparently, and it does not require any special instructions in your programs. Its easy setup and use make INFORMIX-SE an ideal engine for developing small- to medium-size applications that do not require maximum performance nor an extensive range of data-integrity options.
INFORMIX-OnLine is a transaction-processing database engine that manages I/O operations directly so that performance is maximized. It is designed to handle the high performance requirements and integrity concerns of many large applications. Most applications can run on either engine because few differences affect the programmer. INFORMIX-OnLine, however, provides features that increase performance, extend available data types, and improve the administrative aspects of database management. The following features are available only with INFORMIX-OnLine:

Raw I/O and optimized shared memory for greater performance High availability and automatic recovery Increased locking and process isolation options for greater integrity
control

Introduction

Informix Database Engines

Variable-length character data (VARCHARs) Binary Large OBjects (BLOBs) that can be any type or amount of data Distributed query capability across multiple databases Distributed query capability across multiple INFORMIX-OnLine systems, if you have the INFORMIX-STAR add-on product.

INFORMIX-OnLine can substantially improve application performance by using direct I/O to raw storage devices, and by tuning shared memory for maximum efciency. INFORMIX-OnLine offers high data availability, which allows rapid recovery from system failures and provides you with logging choices, including the option of disk mirroring. INFORMIX-OnLine provides advanced concurrency control by allowing you to set the level of locking granularity and the level of user process isolation. INFORMIX-OnLine supports three additional data types not available with INFORMIX-SE. VARCHARs are variable-length character columns (up to 255 bytes) that use disk space only as it is needed. The TEXT and BYTE data types are Binary Large OBjects (BLOBs) capable of holding virtually any type or amount of data. TEXT can store ASCII text les with embedded control characters, such as documents generated through a word processor. BYTE can store any type of binary data, such as spreadsheets, program load modules, digitized images, or voice patterns. INFORMIX-OnLine allows access to multiple databases on the same computer. You can write applications that retrieve data from multiple tables, even if the tables reside in different databases. You can use the combined data for general display purposes or as input to a customized report. INFORMIX-STAR is an optional add-on product to INFORMIX-OnLine that allows you access to multiple INFORMIX-OnLine systems. With INFORMIX-STAR you can write queries that span multiple databases in different INFORMIX-OnLine systems across a network.

This manual provides you with information on how to use INFORMIX-4GL with INFORMIX-SE. If you are planning to use INFORMIX-OnLine, refer to the INFORMIX-OnLine Programmers Manual for information about programming issues. Notes are placed at appropriate locations in this manual to help clarify where INFORMIX-OnLine can provide additional functionality.

Introduction

Summary of Chapters

Summary of Chapters
The INFORMIX-4GL Reference Manual is divided into the following chapters and appendices: Introduction briey describes the INFORMIX-4GL documentation, notational conventions used in syntax statements, and the demonstration database. describes the C Compiler and Rapid Development System implementations of INFORMIX-4GL. It also explains how to create executable versions of 4GL source les, both from the Programmers Environment and at the command line. gives the rules for programming in INFORMIX-4GL. It denes data types and binding of program variables, describes expressions and functions, and explains error handling and the interrelationships among all the INFORMIX-4GL statements. describes how to interact with databases by using the Informix extension to IBMs Structured Query Language (SQL). This chapter also explains the interrelationships among various types of SQL statements and illustrates the use of the 4GL Programmers Environment. describes the procedures to construct and compile 4GL screen form specications. describes the procedures to specify and produce 4GL reports. describes the functions in the INFORMIX-4GL library.

Chapter 1

Chapter 2

Chapter 3

Chapter 4 Chapter 5 Chapter 6

Introduction

Syntax Conventions

Chapter 7

contains an alphabetized description of each of the SQL and INFORMIX-4GL statements that you can use in an INFORMIX-4GL program. Use this chapter as a reference for syntax and rules concerning the use of these statements. describes the stores demonstration database. describes the system catalog tables that form the data dictionary of an INFORMIX-4GL database. describes the environment variables that are used by INFORMIX-4GL.

Appendix A Appendix B Appendix C Appendix D Appendix E

lists the reserved words of INFORMIX-4GL. describes the bcheck, dbload, dbexport, dbimport, dbschema, dbupdate, mkmessage, sqlconv, and upscol utility programs. contains descriptions of C functions that handle DECIMAL type variables in C programs. amplies the Chapter 3 discussion of outer joins. lists the ASCII characters in order. describes modications that you can make to your termcap and terminfo les to extend function key denitions, to specify characters for window borders, and to enable INFORMIX-4GL programs to interact with terminals that support color displays. describes how you can use the DATETIME and INTERVAL data types.

Appendix F Appendix G Appendix H Appendix I

Appendix J

Error Messages contains an extensive listing of error codes, explains their meaning, and suggests remedies for correcting the errors. Index is an alphabetic list of page references for selected 4GL topics in this manual and in its companion, the INFORMIX-4GL User Guide.

Syntax Conventions
This section explains how to interpret the listings of statement syntax that appear throughout this manual.

Introduction

Syntax Conventions

ABC

Enter any term that appears in uppercase letters exactly as shown, disregarding case. Such terms are keywords. For example,
CREATE INDEX indname means you must enter CREATE INDEX or create index without adding or deleting spaces or letters.

abc

Substitute a value for any term that appears in lowercase italic letters. In the previous example, you should substitute a value for indname. In each statement description in Chapter 7, the section Explanation describes what values you can substitute for italicized terms. Enter parentheses as shown. They are part of the syntax of a statement, not special symbols. Unless advised otherwise, do not enter brackets as part of a statement, since they surround any part of a statement that is optional. For example,
CREATE [ UNIQUE ] INDEX

() []

indicates that you can enter either CREATE INDEX or CREATE UNIQUE INDEX. | Select one of the options shown. The vertical bar indicates a choice among several options. For example,
[ ONE | TWO [ THREE ] | FOUR ]

means that you can enter ONE or TWO or FOUR , and that, if you enter TWO, you can also enter THREE. (Because all the choices are enclosed in square brackets, you can also choose to omit them completely.) {} Choose one of the listed options. When the options are enclosed in braces and separated by vertical bars, you must select one of the options. For example,
{ ONE | TWO | THREE }

means that you must enter ONE or TWO or THREE, and that you cannot enter more than one selection. Unless advised otherwise, do not enter braces in a statement. ABC Omit or use an option that is underlined. When one of several options is the default option, it appears underlined. For example:
[ CHOCOLATE | VANILLA | STRAWBERRY ]

means that you can select any of the three options, but that if you do not enter any of them, VANILLA is the default.

10

Introduction

The Demonstration Database

...

Enter additional items like those preceding the ellipsis, if you want. The ellipsis indicates that the immediately preceding item can be repeated indenitely. For example, statement
...

means that there can be a series of statements following the one that is listed. Do not enter ellipsis symbols in a statement or program, unless you want to enter them as literal string values. Enter all other symbols, such as - / ; > . = % : * " and , exactly as they appear in the syntax statement. The notation (O) sometimes follows the name of a statement at the beginning of a syntax description in Chapter 7. This means that additional options or features are supported by INFORMIX-4GL on the INFORMIX-OnLine database engine. Refer to the INFORMIX-OnLine Programmers Manual for details of the additional functionality available with INFORMIX-OnLine.

The Demonstration Database

Most of the examples in this manual are based on the stores demonstration database. This database, which is described and listed in detail in Appendix A, involves a wholesale sporting goods rm that maintains a stock of equipment and lls orders to retailers. You can create the stores database in the current directory by entering i4gldemo (if you have the INFORMIX-4GL C Compiler Version) or by entering r4gldemo (if you have the INFORMIX-4GL Rapid Development System). Each shell script removes any database labeled stores and installs the demonstration database. The stores database contains six tables: customer orders items stock contains information about the retail stores that purchase sporting supplies. contains information about the individual orders from the retail stores. contains information about the items in an order. contains information about the variety of sporting goods available.
Introduction 11

The Demonstration Database

manufact state

contains information about manufacturers of sporting goods. contains the names and abbreviations of U.S. states.

Note: The stores demonstration database includes additional system catalogs and the source code modules of several INFORMIX-4GL application programs.

12

Introduction

Chapter

1
Compiling 4GL Source Files
Chapter Overview 5 The Two Implementations of INFORMIX-4GL INFORMIX-4GL (C Compiler Version) 7 7 5 The Programmers Environment (C Compiler Version) The INFORMIX-4GL Menu 8 The MODULE Design Menu 9 The Modify Option 9 The New Option 12 The Compile Option 12 The Program_Compile Option 13 The Run Option 13 The Exit Option 14 The FORM Design Menu 14 The Modify Option 15 The Generate Option 16 The New Option 17 The Compile Option 17 The Exit Option 18 The PROGRAM Design Menu 18 The Modify Option 19 The New Option 22 The Compile Option 22 The Planned_Compile Option 23 The Run Option 24 The Drop Option 24 The Exit Option 24 The QUERY LANGUAGE Menu 25

Creating Executable 4GL Programs (C Compiler Version) 25 Working in the Programmers Environment 25 Creating a New Source Module 26 Revising an Existing Module 26 Compiling a Source Module 27 Linking Program Modules 28 Executing a Compiled Program 30 Working at the Command Line 30 Creating or Modifying a 4GL Source File 31 Compiling a 4GL Module 31 Compiling and Linking Multiple Source Files 32 Running 4GL Programs 34 4GL Programs That Call C Functions 34 Program Filename Extensions (C Compiler Version) INFORMIX-4GL (Rapid Development System) The RDS Programmers Environment 36 The INFORMIX-4GL Menu 37 The MODULE Design Menu 38 The Modify Option 39 The New Option 41 The Compile Option 41 The Program_Compile Option 41 The Run Option 42 The Debug Option 42 The Exit Option 43 The FORM Design Menu 43 The Modify Option 44 The Generate Option 46 The New Option 46 The Compile Option 47 The Exit Option 47 The PROGRAM Design Menu 48 The Modify Option 49 The New Option 51 The Compile Option 51 The Planned_Compile Option 52 The Run Option 52 The Debug Option 53 The Undene Option 53 The Exit Option 53 The QUERY LANGUAGE Menu 54
1-2 Compiling 4GL Source Files

35

36

Creating Executable RDS Programs 54 Working in the RDS Programmers Environment 54 Creating a New Source Module 55 Revising an Existing Module 55 Compiling a Source Module 56 Combining Program Modules 57 Executing a Compiled RDS Program 58 Invoking the Debugger 59 Working at the RDS Command Line 59 Creating or Modifying a 4GL Source File 61 Compiling an RDS Source File 61 Concatenating Multi-Module Programs 63 Running RDS Programs 64 Running Multi-Module Programs 65 Running Programs with the Interactive Debugger RDS Programs That Call C Functions 66 Editing the fgiusr.c File 67 Creating a Customized Runner 69 Running Programs That Call C Functions 72 RDS Program Filename Extensions 72

65

Compiling 4GL Source Files

1-3

1-4

Compiling 4GL Source Files

Chapter Overview
This chapter describes how to create INFORMIX-4GL source-code modules, and how to produce executable 4GL programs from these source-code modules, both at the operating system prompt and from within the INFORMIX-4GL Programmers Environment. The procedures to do this are described for the INFORMIX-4GL C Compiler Version, as well as for the INFORMIX-4GL Rapid Development System. These two implementations of INFORMIX-4GL differ in how they process 4GL source-code modules.

The Two Implementations of INFORMIX-4GL

To write an INFORMIX-4GL program, you must rst create an ASCII le of 4GL statements that perform logical tasks to support your application. Other chapters and appendixes describe the features of the INFORMIX-4GL application development language, and the use and syntax of its statements and utilities. This chapter explains the procedures by which you can transform one or more source-code les of INFORMIX-4GL statements into an executable 4GL program. Informix Software, Inc., offers two different implementations of the INFORMIX-4GL application development language:

The INFORMIX-4GL C Compiler Version, which uses a preprocessor to

generate INFORMIX-ESQL/C source code. This code is preprocessed in turn to produce C source code, which is then compiled and linked as object code in an executable command le.

The INFORMIX-4GL Rapid Development System, which uses a compiler

to produce pseudo-code (called p-code) in a single step. You then invoke a runner to execute the p-code version of your application. (The INFORMIX-4GL Rapid Development System is sometimes abbreviated as RDS.)

Compiling 4GL Source Files

1-5

The Two Implementations of INFORMIX-4GL

Both implementations use the same INFORMIX-4GL statements, and nearly identical Programmers Environments. Because they use different methods to compile your 4GL source les into executable programs, however, there are a few differences in the user interfaces. These differences are summarized on this page and the next:

Differences in Command Lines

Compiler RDS Effect of Command

i4gl r4gl Enter Programmers Environment c4gl sle.4gl fglpc sle Compile 4GL source le sle.4gl xle.4ge fglgo xle Execute compiled 4GL program xle i4gldemo r4gldemo Create the demonstration database The INFORMIX-4GL C Compiler Version requires no equivalent to the fglgo command, since its compiled object les are executable without a runner. The INFORMIX-4GL Rapid Development System also contains a command-le script to compile and execute 4GL programs that call C functions or INFORMIX-ESQL/C functions, as described near the end of this chapter.

Differences in the Programmers Environment

The Programmers Environment is a system of menus that supports the various steps in the process of developing 4GL application programs. The Drop option on the PROGRAM Design Menu of the C Compiler Version is called Undene in the INFORMIX-4GL Rapid Development System implementation. The New and Modify options of the PROGRAM Design Menu display a different screen form in the two implementations. Both of these screen forms are illustrated later in this chapter. The INFORMIX-4GL Rapid Development System includes a Debug option on its MODULE Design Menu and PROGRAM Design Menu. This option does not appear in the C Compiler Version. (The Debugger is based on p-code, so it can execute programs and modules compiled by the INFORMIX-4GL Rapid Development System). The INFORMIX-4GL Interactive Debugger is available as a separate product.

Differences in Filename Extensions

Compiler .o .4ge RDS .4go .4gi Signicance of Extension Compiled 4GL source-code module Executable (runable) 4GL program le

The backup le extensions .4bo and .4be for compiled modules and programs have the same names in both implementations. These
1-6 Compiling 4GL Source Files

INFORMIX-4GL (C Compiler Version)

designate les that are not interchangeable between the two 4GL implementations, however, because object code produced by a C compiler is different from p-code. Other lename extensions that are the same in both the C Compiler Version and Rapid Development System Version designate interchangeable les, if you use both implementations of INFORMIX-4GL to process the same 4GL source-code module.

INFORMIX-4GL (C Compiler Version)

The rest of this chapter describes in detail both implementations of INFORMIX-4GL. For each implementation, this chapter presents the following information:

It identies and illustrates all the menu options and screen form elds
of the Programmers Environment.

It describes the steps for compiling and executing INFORMIX-4GL

programs from the Programmers Environment.

It describes the equivalent command-line syntax for compiling and

executing INFORMIX-4GL programs.

It identies the lename extensions of 4GL source-code, object, error,

and backup les. The INFORMIX-4GL C Compiler Version is described rst. If you have the INFORMIX-4GL Rapid Development System, skip ahead to the section entitled The RDS Programmers Environment near the middle of this chapter.

The Programmers Environment (C Compiler Version)

The INFORMIX-4GL C Compiler Version provides a series of nested menus, called the Programmers Environment. These menus support the steps of 4GL program development and keep track of the components of your application. You can invoke the Programmers Environment by entering i4gl at the system prompt.

Compiling 4GL Source Files

1-7

The INFORMIX-4GL Menu

The INFORMIX-4GL Menu

The i4gl command briey displays the INFORMIX-4GL banner. Then a menu appears, called the INFORMIX-4GL Menu:
INFORMIX-4GL: Module Form Program Query-language Exit Create, modify, or run individual 4GL program modules. -------------------------------------------------Press CTRL-W for Help------

This is the highest menu, from which you can reach any other menu of the Programmers Environment. You have ve options: Module Form Program Query-language Exit Work on an INFORMIX-4GL program module. Work on a screen form. Specify components of a multi-module program. Use the SQL interactive interface, if you have INFORMIX-SQL installed on your system. Return to the operating system.

The rst three options display new menus that are described in the pages that follow. (You can also press CTRL-W at any menu to display an on-line help message that describes your options.) As at any 4GL menu, you can select an option in either of two ways:

By typing the rst letter of the option, or By using the SPACEBAR or Arrow keys to move the highlight to the option
that you choose, and then pressing RETURN.

1-8

Compiling 4GL Source Files

The MODULE Design Menu

The MODULE Design Menu

You can press RETURN or type m or M to select the Module option of the INFORMIX-4GL Menu. This displays a new menu, called the MODULE Design Menu. Use this menu to work on an individual 4GL source-code module.
MODULE: Modify New Compile Program_Compile Change an existing 4GL program module. Run Exit

-------------------------------------------------Press CTRL-W for Help------

The MODULE Design Menu supports the following options: Modify New Compile Program_Compile Run Exit Change an existing 4GL source-code module. Create a new 4GL source-code module. Compile a 4GL source-code module. Compile a 4GL application program. Execute a compiled 4GL program module or a multimodule application program. Return to the INFORMIX-4GL Menu.

As in all of the menus of the Programmers Environment except the INFORMIX-4GL Menu, the Exit option returns control to the higher menu from which you accessed the current menu. You can use these options to create and compile source-code modules of a 4GL application. See The FORM Design Menu later in this chapter for information on creating 4GL screen forms. See also The mkmessage Utility section in Appendix E for information on how to create and compile programmer-dened help messages for an INFORMIX-4GL application.

The Modify Option

Select this option to edit an existing 4GL source-code module. If you select this option, INFORMIX-4GL requests the name of the 4GL source-code le to be modied and then prompts you to specify a text editor. If you have designated an editor with the DBEDIT environment variable

Compiling 4GL Source Files

1-9

The MODULE Design Menu

(see Appendix C) or named an editor previously in this session at the Programmers Environment, INFORMIX-4GL invokes that editor. The 4GL source le whose lename you specied is the current le. When you leave the editor, INFORMIX-4GL displays the MODIFY MODULE Menu, with the Compile option highlighted:
MODIFY MODULE: Compile Save-and-exit Compile the 4GL module specification. Discard-and-exit

-------------------------------------------------Press CTRL-W for Help------

If you press RETURN or type c or C to select the Compile option, INFORMIX-4GL displays the COMPILE MODULE Menu:
COMPILE MODULE: Object Runable Exit Create object file only; no linking to occur. -------------------------------------------------Press CTRL-W for Help------

The Object option creates a compiled le with the .o extension but makes no attempt to link the le with other les. The Runable option creates a compiled le with the .4ge extension. INFORMIX-4GL assumes that the current module is a complete 4GL program, and that no other module needs to be linked to it. Select the Runable option if the current program module is a stand-alone 4GL program. If this is not the case, (that is, if the le is one of several 4GL source-code modules within a multimodule program), then you should use the Object option instead, and you must use the PROGRAM Design menu to specify all the component modules. After you select Object or Runable, a message near the bottom of the screen will advise you if INFORMIX-4GL issues a compile-time warning or error. If there are warnings (but no errors), an executable le is produced. Select the

1-10

Compiling 4GL Source Files

The MODULE Design Menu

Exit option of the next menu, and then Save-and-exit at the MODIFY MODULE Menu, if you want to save the executable le without reading the warnings. Alternatively, you can examine the warning messages by selecting Correct at the next menu. When you nish editing the .err le that contains the warnings, you must select Compile again from the MODIFY MODULE Menu, since the Correct option deletes the executable le. If there are compilation errors, the following menu appears:
COMPILE MODULE: Correct Exit Correct errors in the 4GL module. -------------------------------------------------Press CTRL-W for Help------

If you choose to correct the errors, an editing session begins on a copy of your source module with embedded error messages. You do not need to delete the error messages, since INFORMIX-4GL does this for you. Correct your source le, save your changes, and exit from the editor. The MODIFY MODULE Menu reappears, prompting you to recompile, or to save or discard your changes without compiling. If there are no compilation errors, the MODIFY MODULE Menu appears with the Save-and-Exit option highlighted. Select this option to save the current source-code module as a le with extension .4gl, and create an object le with the same lename, but with the extension .o. If you specied Runable when you compiled, the executable version is saved with the extension .4ge. The Discard-and-Exit option discards any changes to your le since you selected the Modify option.

Compiling 4GL Source Files 1-11

The MODULE Design Menu

The New Option

Select this option to create a new 4GL source-code module.
MODULE: Modify New Compile Program_Compile Create a new 4GL program module. Run Exit

-------------------------------------------------Press CTRL-W for Help------

This option resembles the Modify option, but NEW MODULE is the menu title, and you must enter a new module name, rather than select it from a list. If you have not designated an editor previously in this session or with DBEDIT, you are prompted for an editor. Then an editing session begins.

The Compile Option

The Compile option enables you to compile an individual 4GL source-code module without rst selecting the Modify option.
MODULE: Modify New Compile Program_Compile Compile an existing 4GL program module. Run Exit

-------------------------------------------------Press CTRL-W for Help------

After you specify the name of a 4GL source-code module to compile, the screen displays the COMPILE MODULE Menu. Its Object, Runable, and Exit options were described earlier in the discussion of the Modify option.

1-12

Compiling 4GL Source Files

The MODULE Design Menu

The Program_Compile Option

The Program_Compile option of the MODULE Design Menu is the same as the Compile option of the PROGRAM Design Menu. (See that option for details.) You can use this option to compile and link modules, as described in the program specication database, taking into account the time when the modules were last updated. This option is useful when you have just modied a single module of a complex program, and need to test it by compiling and linking it with the other modules.

The Run Option

Select this option to begin execution of a compiled program.
MODULE: Modify New Compile Program_Compile Run Exit Execute an existing 4GL program module or application program. -------------------------------------------------Press CTRL-W for Help------

The RUN PROGRAM screen presents a list of compiled modules and programs, with the highlight on the module corresponding to the current le, if any has been specied. Compiled programs must have the extension .4ge to be included in the list. If you compile a program outside the Programmers Environment and you want it to appear in the program list, give it the extension .4ge. If no compiled programs exist, INFORMIX-4GL displays an error message and restores the MODULE Design Menu.

Compiling 4GL Source Files

1-13

The FORM Design Menu

The Exit Option

Select this option to exit from the MODULE Design Menu and display the INFORMIX-4GL Menu.
MODULE: Modify New Compile Program_Compile Returns to the INFORMIX-4GL Menu. Run Exit

-------------------------------------------------Press CTRL-W for Help------

The FORM Design Menu

You can type f or F at the INFORMIX-4GL Menu to select the Form option. This option displays a menu, called the FORM Design Menu:
FORM: Modify Generate New Compile Exit Change an existing form specification. -------------------------------------------------Press CTRL-W for Help------

You can use this menu to create, modify, and compile screen form specications. These dene visual displays that 4GL applications can use to query and modify the information in a database. INFORMIX-4GL form specication les are ASCII les that are described in Chapter 4 of this manual, and in Chapters 6 and 7 of the INFORMIX-4GL User Guide. The FORM Design Menu supports the following options: Modify Generate New Compile Exit Change an existing 4GL screen form specication. Create a default 4GL screen form specication. Create a new 4GL screen form specication. Compile an existing 4GL screen form specication. Return to the INFORMIX-4GL Menu.

1-14

Compiling 4GL Source Files

The FORM Design Menu

Readers familiar with INFORMIX-SQL may notice that this resembles the menu displayed by the Form option of the INFORMIX-SQL Main Menu.

The Modify Option

The Modify option of the FORM Design Menu enables you to edit an existing form specication le. It resembles the Modify option in the MODULE Design Menu, since both options are used to edit program modules.
FORM: Modify Generate New Compile Exit Change an existing form specification. -------------------------------------------------Press CTRL-W for Help------

If you select this option, you are prompted to select the name of a form specication le to modify. Source les created at the FORM Design Menu have the le extension .per. (If you use a text editor outside of the Programmers Environment to create form specication les, you must give them the extension .per before you can compile them with the FORM4GL screen form facility.) If you have not already designated a text editor in this INFORMIX-4GL session or with DBEDIT, you are prompted for the name of an editor. Then an editing session begins, with the form specication source-code le that you specied as the current le. When you leave the editor, INFORMIX-4GL displays the MODIFY FORM Menu with the Compile option highlighted. Now you can press RETURN to compile the revised form specication le.
MODIFY FORM: Compile Save-and-exit Compile the form specification. Discard-and-exit

-------------------------------------------------Press CTRL-W for Help------

Compiling 4GL Source Files

1-15

The FORM Design Menu

If there are compilation errors, INFORMIX-4GL displays the COMPILE FORM Menu:
COMPILE FORM: Correct Exit Correct errors in the form specification. -------------------------------------------------Press CTRL-W for Help------

Press RETURN to select Correct as your option. An editing session begins on a copy of the current form, with diagnostic error messages embedded where the compiler detected syntax errors. INFORMIX-4GL automatically deletes these messages when you save and exit from the editor. After you have corrected the errors, the MODIFY FORM Menu appears again, with the Compile option highlighted. Press RETURN to recompile. Repeat these steps until the compiler reports no errors. If there are no compilation errors, you are prompted whether to save the modied form specication le and the compiled form, or to discard the changes. (Discarding the changes restores the version of your form specications from before you chose the Modify option.)

The Generate Option

You can type g or G to select the Generate option. This option creates a simple default screen form that you can use directly in your program, or that you can later edit by selecting the Modify option.
FORM: Modify Generate New Compile Exit Generate and compile a default form specification. -------------------------------------------------Press CTRL-W for Help------

1-16

Compiling 4GL Source Files

The FORM Design Menu

When you select this option, INFORMIX-4GL prompts you to select a database, to choose a lename for the form specication, and to identify the tables that the form will access. After you provide these data, INFORMIX-4GL creates and compiles a form specication le. (This is equivalent to running the -d (default) option of FORM4GL, as described near the end of Chapter 4, Form Building and Compiling.)

The New Option

The New option of the FORM Design Menu enables you to create a new screen form specication.
FORM: Modify Generate New Compile Create a new form specification. Exit

-------------------------------------------------Press CTRL-W for Help------

After prompting you for the name of your form specication le, INFORMIX-4GL places you in the editor where you can create a form specication le. When you leave the editor, INFORMIX-4GL transfers you to the NEW FORM Menu that is like the MODIFY FORM Menu. You can compile your form and correct it in the same way.

The Compile Option

The Compile option enables you to compile an existing form specication le without going through the Modify option.
FORM: Modify Generate New Compile Exit Compile an existing form specification. -------------------------------------------------Press CTRL-W for Help------

Compiling 4GL Source Files

1-17

The PROGRAM Design Menu

INFORMIX-4GL compiles the form specication le whose name you specify. If the compilation fails, INFORMIX-4GL displays the COMPILE FORM Menu

with the highlight on the Correct option.

The Exit Option

The Exit option restores the INFORMIX-4GL Menu.
FORM: Modify Generate New Compile Returns to the INFORMIX-4GL Menu. Exit

-------------------------------------------------Press CTRL-W for Help------

The PROGRAM Design Menu

An INFORMIX-4GL program can be a single source-code module that you create and compile at the MODULE Design Menu. For applications of greater complexity, however, it is often easier to develop and maintain separate 4GL modules. The INFORMIX-4GL Menu includes the Program option so that you can create multi-module programs. If you select this option, INFORMIX-4GL searches your DBPATH directories (see Appendix C) for the program specication database, called syspgm4gl. This database describes the component modules and function libraries of your 4GL program. If INFORMIX-4GL cannot nd this database, you are asked if you want one created. If you enter y in response, INFORMIX-4GL creates the syspgm4gl database, grants CONNECT privilege to PUBLIC, and displays the PROGRAM Design Menu. As Database Administrator of syspgm4gl, you can later restrict the access of other users.

1-18

Compiling 4GL Source Files

The PROGRAM Design Menu

If syspgm4gl already exists, the PROGRAM Design Menu appears.

PROGRAM: Modify New Compile Planned_Compile Run Drop Exit Change the compilation definition of a 4GL application program. -------------------------------------------------Press CTRL-W for Help------

You can use this menu to create or modify a multi-module 4GL program specication, to compile and link a program, or to execute a program. The PROGRAM Design Menu supports the following options: Modify New Compile Planned_Compile Run Drop Exit Change an existing program specication. Create a new program specication. Compile an existing program. List the steps necessary to compile and link an existing program. Execute an existing program. Delete an existing program specication. Return to the INFORMIX-4GL Menu.

You must rst use the MODULE Design Menu and FORM Design Menu to enter and edit the INFORMIX-4GL statements within the component sourcecode modules of a 4GL program. Then you can use the PROGRAM Design Menu to identify which modules are part of the same application program, and to link all the modules as an executable command le.

The Modify Option

The Modify option enables you to modify the specication of an existing 4GL program. (This option is not valid unless at least one program has already been specied. If none has, you can create a program specication by selecting the New option from the same menu.) INFORMIX-4GL prompts you for

Compiling 4GL Source Files

1-19

The PROGRAM Design Menu

the name of the program specication to be modied. It then displays a menu and form that you can use to update the information in the program specication database as shown in Figure 1-1:
MODIFY PROGRAM: 4GL Other Edit the 4GL sources list. Libraries Compile_Options Rename Exit

-------------------------------------------------Press CTRL-W for Help-----Program [myprog ] 4gl Source [main [funct [rept [ [ 4gl Source Path [/u/john/appl/4GL [/u/john/appl/4GL [/u/john/appl/4GL [ [ Ext [c [ [ [ Other Source Path [/u/john/appl/C [ [ [ Compile Options [ [ ] ]

] ] ] ] ]

] ] ] ] ]

Other Source [cfunc ] [ ] [ ] [ ] Libraries [m [

] ] ] ] ] ]

] ] ] ]

Figure 1-1

Example of a Program Specication Entry

The name of the program appears in the Program eld. In Figure 1-1 the name is myprog. You can change this name by selecting the Rename option. INFORMIX-4GL assigns the program name, with the extension .4ge, to the executable program produced by compiling and linking all the source les and libraries. (Compiling and linking occurs when you select the Compile option, as described later in this chapter.) In this example, the resulting executable program would have the name myprog.4ge. Use the 4GL option to update the entries for the 4GL Source elds and the 4GL Source Path elds on the form. The ve rows of elds under these labels form a screen array. When you select the 4GL option, INFORMIX-4GL executes an INPUT ARRAY statement so you can move and scroll through the array. See the INPUT ARRAY statement in Chapter 7 for information about how to use your function keys to scroll, delete rows, and insert new rows. (You cannot redene the function keys, however, as you can with an INFORMIX-4GL program.)

1-20

Compiling 4GL Source Files

The PROGRAM Design Menu

The INFORMIX-4GL source program that appears in Figure 1-1 contains three modules:

One module contains the main program (main.4gl). One module contains functions (funct.4gl). One module contains REPORT statements (rept.4gl).
Each module is located in the directory /u/john/appl/4GL. If your program includes a module containing only global variables (for example, global.4gl), you must also list that module in this section. Use the Other option to include non-INFORMIX-4GL source modules or object-code modules in your program. Enter this information into the three-column screen array with the headings Other Source, Ext, and Other Source Path. Enter the lename and location of each non-INFORMIX-4GL source-code or object-code module in these elds. Enter the name of the module in the Other Source eld, the lename extension of the module (for example, ec for an INFORMIX-ESQL/C module, or c for a C module) in the Ext eld, and the full directory path of the module in the Other Source Path eld. The example in Figure 1-1 includes a le containing C function sourcecode (cfunc.c) located in /u/john/appl/C. You can list up to 100 les in this array. The Libraries option enables you to indicate the names of up to ten special libraries to link with your program. INFORMIX-4GL calls the C compiler to do the linking and adds the appropriate -l prex, so you should enter only what follows the prex. The example displayed in Figure 1-1 calls only the standard C math library. Use the Compile_Options option to indicate up to ten C compiler options. Enter this information in the Compile Options eld. You cannot, however, specify the -e or -a options of c4gl in this eld. (See the section Working at the Command Line for more information about the options of the c4gl command). The Exit option exits from the MODIFY PROGRAM Menu and displays the PROGRAM Design Menu.

Compiling 4GL Source Files

1-21

The PROGRAM Design Menu

The New Option

Use the New option on the PROGRAM Design Menu to create a new specication of the program modules and libraries that make up an application program. You can also specify any necessary compiler or loader options.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit Add the compilation definition of a 4GL application program. -------------------------------------------------Press CTRL-W for Help------

The submenu screen forms displayed by the New and the Modify options of the PROGRAM Design Menu are identical, except that you must rst supply a name for your program when you select the New option. (INFORMIX-4GL displays a blank form in the NEW PROGRAM Menu.) The NEW PROGRAM Menu has the same options as the MODIFY PROGRAM Menu, as illustrated earlier.

The Compile Option

The Compile option performs the compilation and linking described in the program specication database, taking into account the time when each le was last updated. It compiles only those les that have not been compiled since they were changed.
PROGRAM: Modify New Compile Planned_Compile Compile a 4GL application program. Run Drop Exit

-------------------------------------------------Press CTRL-W for Help------

INFORMIX-4GL lists each step of the preprocessing and compilation as it

occurs. An example of these messages appears in the illustration of The Planned_Compile Option in the next section.

1-22

Compiling 4GL Source Files

The PROGRAM Design Menu

The Planned_Compile Option

Taking into account the time when the various les in the dependency relationships last changed, the Planned_Compile option prompts for a program name and displays a summary of the steps that will be executed if you select the Compile option. No compilation actually takes place.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit Show the planned compile actions of a 4GL application program. -------------------------------------------------Press CTRL-W for Help-----Compiling INFORMIX-4GL sources: /u/john/appl/4GL/main.4gl /u/john/appl/4GL/funct.4gl /u/john/appl/4GL/rept.4gl Compiling Embedded SQL sources: Compiling with options: Linking with libraries: m Compiling/Linking other sources: /u/john/appl/C/cfunc.c

In this instance, changes were made to all the components of the 4GL program that were listed in Figure 1-1. This display indicates that no source-code module has been compiled since the program was changed.

Compiling 4GL Source Files

1-23

The PROGRAM Design Menu

The Run Option

The Run option of the PROGRAM Design Menu is the same as the Run option of the MODULE Design Menu. It displays a list of any compiled programs (les with the extension .4ge) and positions the highlight on the current program, if a program has been specied. INFORMIX-4GL then executes the program that you select.
PROGRAM: Modify New Compile Planned_Compile Execute a 4GL application program Run Drop Exit

-------------------------------------------------Press CTRL-W for Help------

The Drop Option

The Drop option of the PROGRAM Design Menu prompts you for a program name and removes the compilation and linking denition of that program from the syspgm4gl database. This action removes the denition only. Your program and 4GL modules are not removed.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit Drop the compilation definition of a 4GL application program. -------------------------------------------------Press CTRL-W for Help------

The Exit Option

The Exit option clears the PROGRAM Design Menu and restores the INFORMIX-4GL Menu.

1-24

Compiling 4GL Source Files

The QUERY LANGUAGE Menu

The QUERY LANGUAGE Menu

The SQL interactive interface is identical to the interactive SQL interface of INFORMIX-SQL. You can use this option only if you have separately purchased INFORMIX-SQL and installed it. The Query-language option is placed at the top-level menu so you can test SQL statements without leaving the INFORMIX-4GL Programmers Environment. You can also use this option to create, execute, and save SQL scripts.

Creating Executable 4GL Programs (C Compiler Version)

To create a 4GL application with the C Compiler Version of INFORMIX-4GL requires the following steps: 1. Preprocess INFORMIX-4GL code to produce INFORMIX-ESQL/C code. 2. Preprocess the INFORMIX-ESQL/C code to produce C language code. 3. Compile the C code with the C compiler to create an object le. 4. Link the object le with the INFORMIX-ESQL/C libraries, and to any additional libraries whose functions are called. The sections that follow describe how to carry out these steps, both from the Programmers Environment and at the system prompt.

Working in the Programmers Environment

If your software has been installed according to the instructions in your Installation Guide, you can enter i4gl at the system prompt to invoke the Programmers Environment. After a pause for the sign-on message, the INFORMIX-4GL Menu appears.

Compiling 4GL Source Files

1-25

Working in the Programmers Environment

Creating a New Source Module

This section outlines the procedure for creating a new module. If your source module already exists but needs to be modied, you should skip ahead to the next section, Revising an Existing Module.

Press RETURN at the INFORMIX-4GL Menu to select the Module option.

The screen displays the MODULE Design Menu.

If you are creating a new .4gl source module, press n to select the New
option of the MODULE Design Menu. The screen prompts you for a name to assign to the new module.

Enter a name for the new module. The name must begin with a letter and
can include letters, numbers, and underscores. The name must be unique among the les in the same directory, and among the other program modules, if it will be part of a multi-module program. INFORMIX-4GL attaches extension .4gl to this identier, as the lename of your new source module.

Revising an Existing Module

If you are revising an existing 4GL source le, rather than creating a new one, the procedures to begin an editing session are slightly different from the steps that were just described.

Select the Modify option of the MODULE Design Menu. The screen lists the names of all the .4gl source modules in the current
directory and prompts you to select a source le to edit. Use the Arrow keys to highlight the name of a source module and press RETURN, or enter a lename (with no extension). If you specied the name of an editor with the DBEDIT environment variable, an editing session with that editor begins automatically. Otherwise, the screen prompts you to specify a text editor.

Specify the name of a text editor, or press RETURN for vi, the default
editor. Now you can begin an editing session by entering 4GL statements. (The chapters that follow describe INFORMIX-4GL statements and programs.)

When you have nished entering or editing your 4GL code, use an
appropriate editor command to save your source le and end the text editing session.

1-26

Compiling 4GL Source Files

Working in the Programmers Environment

Compiling a Source Module

The .4gl source le module that you create or modify is an ASCII le that must be compiled before it can be executed. After you save your le and exit from the editor, the screen prompts you to choose among Compile, Save-and-exit, or Discard-and-exit options.

Select the Compile option to compile the module. After you select
Compile, the screen prompts you to select among three options: Object, Runable, and Exit. What you should do depends on whether your module is a complete program, or whether it is one of several .4gl modules that together comprise a complete program.

If the module is a complete 4GL program that requires no other modules,

select Runable. This option rst creates an intermediate ESQL/C version of your source-code module, then calls the ESQL/C preprocessor which produces C output, and nally calls the C compiler to produce a compiled le with the same lename, but with the extension .4ge.

If the module is one module of a multi-module 4GL program, select

Object. This option creates a compiled object le module, with the same lename, but with extension .o. See also the procedures for linking program modules, which are described later in this section. If the compiler detects errors after either option, no compiled le is created, and the screen prompts you to select Correct or Exit. Follow the rst two steps on the next page after an error.

Select Correct to resume the previous text editing session, with the same
4GL source code, but with error messages in the le.

Edit the le to correct the error, and select Compile again. If an error message appears, repeat the previous steps, until the module compiles without error.

After the module compiles successfully, the screen prompts you again to
Compile, or to Save-and-exit, or to Discard-and-exit. Select the second option, to save the compiled program. The MODULE Design Menu appears again on your screen.

If your program requires screen forms, you must select Exit to return to the
INFORMIX-4GL Menu, and then select Form to display the FORM Design

Menu. See Chapter 4 for information about designing and creating screen forms.

If your program displays help messages, you must create a help le and
compile it with the mkmessage utility. See Chapter 8 of the INFORMIX-

Compiling 4GL Source Files

1-27

Working in the Programmers Environment

4GL User Guide for more information about help messages in INFORMIX-4GL programs.

Linking Program Modules

If the module that you compiled is the only module in your program, you are now ready to run your program, and you can skip the steps that are described here. If your new or modied module is part of a multi-module 4GL program, however, you must link all of the modules into a single program le before you can run the program.

If you are not at the INFORMIX-4GL Menu, select Exit until that menu
appears. Then select the Program option, to display the PROGRAM Design Menu.

Select the New option if you are creating a new multi-module 4GL
program, or select Modify if you are modifying an existing one. In either case, the screen prompts you for the name of a program.

Enter the name (without a le extension) of the program that you are
modifying, or the name to be assigned to a new program. Names must begin with a letter, and can include letters, underscores ( _ ), and numbers. After you enter a valid name, the PROGRAM screen appears, with your program name in the rst eld. If you selected Modify, the names and pathnames of the source-code modules are also displayed. In that case, the PROGRAM screen appears below the MODIFY PROGRAM Menu, rather than below the NEW PROGRAM Menu. (Both menus list the same options.)

1-28

Compiling 4GL Source Files

Working in the Programmers Environment

MODIFY PROGRAM: 4GL Other Libraries Compile_Options Rename Exit Edit the 4GL sources list. -------------------------------------------------Press CTRL-W for Help-----Program [ ] 4gl Source [ ] [ ] [ ] [ ] [ ] Other Source [ ] [ ] [ ] [ ] Libraries [ [ 4gl Source Path [ [ [ [ [ Ext [ [ [ [ ] ] ] ] ] ] Other Source Path [ [ [ [ Compile Options [ [ ] ] ] ] ] ] ] ] ] ] ]

To specify new 4GL modules or edit the list of 4GL modules, press
RETURN to select the 4GL option. You can enter or edit the name of a

module, without the .4gl le extension. Repeat this step for every module. If the module is not in the current directory nor in a directory specied by the DBPATH environment variable, enter the pathname to the directory where the module resides.

If your program includes any modules that are not 4GL source les, you
should select the Other option. This option enables you to specify each lename in the Other Source eld, the lename extension in the Ext eld, and the pathname in the Other Source Path eld. These elds are part of an array that can specify up to 100 other modules, such as C language source les or object les. If you have the INFORMIX-ESQL/C product installed on your system, you can also specify ESQL/ C source modules (with extension .ec) here.

To specify any function libraries that should be linked to your program

(besides the INFORMIX-4GL library that is described in Chapter 6), select the Libraries option. This option enables you to enter or edit the list of library names in the Libraries elds.

Select the Compile_Options option if you want to specify compiler ags.

These ags can be entered or edited in the Compile Options elds.

After you have correctly listed all of the modules of your program, select
the Exit option to return to the PROGRAM Design Menu.

Compiling 4GL Source Files

1-29

Working at the Command Line

Select the Compile option of the PROGRAM Design Menu. This option
produces an executable le that contains all your 4GL program modules. Its lename is the program name that you specied, with extension .4ge. The screen lists the names of your .4gl source modules, and displays the PROGRAM Design Menu with the Run option highlighted. See also the section Program Filename Extensions (C Compiler Version) later in this chapter for information about the backup les that are produced automatically when you work at the Programmers Environment of the INFORMIX-4GL C Compiler Version.

Executing a Compiled Program

After compiling and linking your program modules, you can type r or R or press RETURN to select the Run option. This option begins execution of the compiled 4GL program. Your program can display menus, screen forms, windows, or other screen output according to your program logic and your keyboard interaction with the program.

Working at the Command Line

You can also create .4gl source les and compiled .o and .4ge les at the operating system prompt. Figure 1-2 shows the process of creating, compiling, linking, and running an INFORMIX-4GL program from the command line.

TEXT EDITOR

.4gl Source Files

.c, .ec Files

.o Object Files

.err Error File

Figure 1-2 1-30

PREPROCESSOR & COMPILER c4gl

.4ge Compiled Program File

Creating and Running an INFORMIX-4GL Program

Compiling 4GL Source Files

Working at the Command Line

Here the rectangles represent processes controlled by specic commands, and the circles represent les. Arrows indicate whether a le can serve as input or output (or as both) for a process. This diagram is simplied and ignores the similar processes by which forms, help messages, and other components of 4GL applications are compiled, linked, and executed.

The cycle begins in the upper left corner with a text editor, such as vi,
to produce a 4GL source module.

A multi-module program can include additional 4GL source les (.4gl),

INFORMIX-ESQL/C source les (.ec), C language source les (.c), and

object les (.o).

The program module can then be compiled, by invoking the c4gl preprocessor and compiler command. (If error messages result, nd them in the .err le and edit the source le to correct the errors. Then recompile the corrected source module.) The resulting compiled .4ge program le is an executable command le that you can run by entering its name at the system prompt: lename.4ge where lename.4ge species your compiled 4GL le. The correspondence between commands and menu options of the Programmers Environment is summarized by the following list:
Command

vi c4gl lename.4ge

Invokes UNIX System Editor 4GL Preprocessor/Compiler 4GL Application

Menu Option Module New/Modify Compile Run

Creating or Modifying a 4GL Source File

Use your system editor or another text editing program to create a .4gl source le or to modify an existing le. See the documentation of your text editor and the other chapters of this manual for details.

Compiling a 4GL Module

You can compile an INFORMIX-4GL source le at the system prompt by entering a command of the form: c4gl source.4gl -o lename.4ge

Compiling 4GL Source Files

1-31

Working at the Command Line

The c4gl command compiles your 4GL source-code module (here called source.4gl) and produces an executable program called lename.4ge. The complete syntax of the c4gl command appears on the next page.

Compiling and Linking Multiple Source Files

An INFORMIX-4GL program can include several source-code modules. You cannot execute a 4GL program until you have preprocessed and compiled all the source modules and linked them with any function libraries that they reference. You can do all this in a single step at the system prompt by the c4gl command, which performs the following processing steps: 1. Reads your 4GL source-code les (extension .4gl) and preprocesses them to produce ESQL/C code. 2. Reads the ESQL/C code and preprocesses it to produce C code. 3. Reads the C code and compiles it to produce an object le. 4. Links the object le to the INFORMIX-ESQL/C libraries and to any additional libraries that you specify in the command line. You must assign the lename extension .4gl to any INFORMIX-4GL sourcecode modules that you compile. The resulting .4ge le is an executable version of your program. Notice that ESQL/C source les (with extension .ec), C source les (with extension .c), and C object les (with extension .o) are intermediate steps in producing an executable INFORMIX-4GL program. Besides 4GL source les (with extension .4gl), you can also include les of any or all of these types when you specify a c4gl command line to compile and link the component modules of a 4GL program. The c4gl command supports the following syntax:

Syntax
c4gl { -V | [ -ansi] [-e ] [ -a ] [ -otherargs . . . ] [ -o outle ] source.4gl . . . [ otheresql.ec . . . ] [ othersrc.c . . . ] [ otherobj.o . . . ] [ yourlib . . . ] }

Explanation
-V -ansi displays the release version number of your SQL software, without processing any source les. instructs the compiler to check all SQL statements for compliance with ANSI standards.

1-32

Compiling 4GL Source Files

Working at the Command Line

-e -a

performs only the preprocessor steps, with no compilation or linking. causes your compiled program to check array bounds at run time. The -a option must appear on the command line before the source.4gl lename. are other arguments for your C compiler. is a name that you assign to the compiled 4GL program. is the name of an INFORMIX-4GL source module. You must specify the .4gl extension. is an ESQL/C source le to compile and link. is a C language source le to compile and link. is an object le to link with your 4GL program. is a library from which to extract functions that are not part of the INFORMIX-4GL or INFORMIX-ESQL/C libraries.

-otherargs outle source.4gl otheresql.ec othersrc.c otherobj.o yourlib

Notes
1. If you specify the -V option to display the version number, all other arguments are ignored, and no output les are produced. 2. Since the -a option requires additional run-time processing, you may want to use this option only during development to debug your program. 3. The c4gl command passes all C compiler arguments (otherargs) and other C source and object les (othersrc.c, otherobj.o) directly to the C compiler (cc). 4. You can compile INFORMIX-4GL modules separately from your MAIN program block. If there is no MAIN program block in source.4gl, your code is compiled to source.o, but not linked with other modules or libraries. You can use c4gl to link your code with a module that includes the MAIN program block at another time. (Chapter 2 of the INFORMIX-4GL User Guide describes the MAIN program block.) 5. If you specify the -ansi option, it must appear rst in your list of c4gl command arguments. The -ansi option asks for compile-time warning messages if your source code includes Informix extensions to the ANSI standard for SQL. (Chapter 7 lists the Informix syntax extensions.) Compiler warnings and error messages are saved in a le called source.err. 6. If you omit the -o outle option, the default lename is a.out.

Compiling 4GL Source Files

1-33

Working at the Command Line

Examples
The simplest case is to compile a single-module INFORMIX-4GL program. This command produces an executable program called single.4ge:
c4gl single.4gl -o single.4ge

In the next example, the object les mod1.o, mod2.o, and mod3.o are previously compiled INFORMIX-4GL modules, and mod4.4gl is a source-code module. Suppose that you want to compile and link mod4.4gl with the three object modules to create an executable program called myappl.4ge. To do so, enter the following command line:
c4gl mod1.o mod2.o mod3.o mod4.4gl -o myappl.4ge

Running 4GL Programs

As noted in the previous section, a valid c4gl command line produces a .4ge le (or whatever you specify after the -o argument) that is an executable command le. To execute your compiled INFORMIX-4GL application program, enter the lename at the system prompt. For example, to run myappl.4ge (the program in the previous example), simply enter the command line: myappl.4ge (Some INFORMIX-4GL programs may require additional command-line arguments, such as constants or lenames, depending on the logic of your specic 4GL application.)

4GL Programs That Call C Functions

No special procedures are needed to create, compile, and execute 4GL programs that call C functions or INFORMIX-ESQL/C functions when you use the C Compiler Version of INFORMIX-4GL. See, however, the section C Functions in Chapter 2 for details of creating INFORMIX-4GL programs that call programmer-dened C functions within 4GL modules. See also Appendix F, DECIMAL Functions for C, which addresses issues of data conversion.

1-34

Compiling 4GL Source Files

Program Filename Extensions (C Compiler Version)

Program Filename Extensions (C Compiler Version)

Source, runable, error, and backup les generated by INFORMIX-4GL are stored in the current directory and are labeled with a lename extension. The following list shows the le extensions for the source, runable, and error les. These les are produced during the normal course of using the C Compiler Version of INFORMIX-4GL. le.4gl le.o le.4ge le.err is an INFORMIX-4GL source le. is an INFORMIX-4GL object le. is an INFORMIX-4GL executable (runable) le. is an INFORMIX-4GL source error le, created when an attempt to compile a module fails. The le contains INFORMIX-4GL source code, plus any compiler syntax error or warning messages. is an intermediate source le, created during the normal course of compiling an INFORMIX-4GL module. is an intermediate C le, created during the normal course of compiling an INFORMIX-4GL module. is an INFORMIX-4GL object error le, created when an attempt to compile or to link a non-INFORMIX-4GL sourcecode or object module fails. The le contains INFORMIX-4GL source code and annotated compiler errors. is a FORM4GL source le. is a FORM4GL object le. is a FORM4GL source error le.

le.ec le.c le.erc

form.per form.frm form.err

The last three les do not exist unless you create or modify a screen form specication le, as described in Chapter 4. The next page lists the corresponding le extensions for the backup les that INFORMIX-4GL automatically creates when you use the Programmers Environment to process 4GL source les. The following list identies the backup les that are produced when you use INFORMIX-4GL from the Programmers Environment. le.4bl le.4bo is an INFORMIX-4GL source backup le, created during the modication and compilation of a .4gl program module. is an object backup le, created during the compilation of a .o program module.

Compiling 4GL Source Files

1-35

INFORMIX-4GL (Rapid Development System)

le.4be le.pbr le.fbm

is an object backup le, created during the compilation of a .4ge program module. is a FORM4GL source backup le. is a FORM4GL object backup le.

Under normal conditions, INFORMIX-4GL creates the backup les and intermediate les as necessary and deletes them upon a successful compilation. If you interrupt a compilation, you may nd one or more of these les in your current directory. During the compilation process, INFORMIX-4GL stores a backup copy of the le.4gl source le in le.4bl. The time stamp is modied on the (original) le.4gl source le, but not on the backup le.4bl le. In the event of a system crash, you may need to replace the modied le.4gl le with the backup copy contained in the le.4bl le. The Programmers Environment does not allow you to begin modifying a .4gl or .per source le if the corresponding backup le already exists in the same directory. After an editing session terminates abnormally, for example, you must delete or rename any backup le before you can resume editing your 4GL module or form from the Programmers Environment.

INFORMIX-4GL (Rapid Development System)

The rest of this chapter provides a description of the INFORMIX-4GL Rapid Development System. Except as otherwise noted, the other chapters and appendixes of this manual describe features that are identical in both the C Compiler Version and Rapid Development System Version implementations of INFORMIX-4GL.

The RDS Programmers Environment

The INFORMIX-4GL Rapid Development System provides a series of menus called the Programmers Environment. These menus support the steps of 4GL program development and keep track of the components of your application. You can invoke the Programmers Environment by entering r4gl at the system prompt.

1-36

Compiling 4GL Source Files

The INFORMIX-4GL Menu

The INFORMIX-4GL Menu

The r4gl command briey displays the INFORMIX-4GL banner and sign-on message. Then a menu appears, called the INFORMIX-4GL Menu:
INFORMIX-4GL: Module Form Program Query-language Exit Create, modify or run individual 4GL program modules. -------------------------------------------------Press CTRL-W for Help------

This is the highest menu, from which you can reach any other menu of the Programmers Environment. You have ve options: Module Form Program Query-language Exit Work on an INFORMIX-4GL program module. Work on a screen form. Specify components of a multi-module program. Use the SQL interactive interface, if you have INFORMIX-SQL installed on your system. Return to the operating system.

The rst three options display new menus that are described in the pages that follow. (You can also press CTRL-W at any menu to display an on-line help message that describes your options.) As at any 4GL menu, you can select an option in either of two ways:

By typing the rst letter of the option, or By using the SPACEBAR or Arrow keys to move the highlight to the option
that you choose, and then pressing RETURN.

Compiling 4GL Source Files

1-37

The MODULE Design Menu

The MODULE Design Menu

You can press RETURN or type m or M to select the Module option of the INFORMIX-4GL Menu. This option displays a new menu, called the MODULE Design Menu. Use this menu to work on an individual 4GL source-code le.
MODULE: Modify New Compile Program_Compile Change an existing 4GL program module. Run Debug Exit

-------------------------------------------------Press CTRL-W for Help------

The MODULE Design Menu supports the following options: Modify New Compile Program_Compile Run Debug Change an existing 4GL source-code module. Create a new 4GL source-code module. Compile an existing 4GL source-code module. Compile a 4GL application program. Execute a compiled 4GL module or multi-module application program. Invoke the INFORMIX-4GL Interactive Debugger to examine an existing 4GL program module or application program (if you have the Debugger product installed on your system). Return to the INFORMIX-4GL Menu.

Exit

As in all of the menus of the Programmers Environment except the INFORMIX-4GL Menu, the Exit option returns control to the higher menu from which you accessed the current menu. You can use these options to create and compile source-code modules of a 4GL application. (See The FORM Design Menu later in this chapter for information on creating 4GL screen forms. Refer also to The mkmessage Utility section of Appendix E for information on creating and compiling programmer-dened help messages for an INFORMIX-4GL application.)

1-38

Compiling 4GL Source Files

The MODULE Design Menu

The Modify Option

Select this option to edit an existing 4GL source-code module. If you select this option, INFORMIX-4GL requests the name of the 4GL source-code le to be modied, and then prompts you to specify a text editor. If you have designated an editor with the DBEDIT environment variable (see Appendix C) or named an editor previously in this session at the Programmers Environment, INFORMIX-4GL invokes that editor. The 4GL source le whose lename you specied is the current le. When you leave the editor, INFORMIX-4GL displays the MODIFY MODULE Menu, with the Compile option highlighted:
MODIFY MODULE: Compile Save-and-exit Compile the 4GL module specification. Discard-and-exit

-------------------------------------------------Press CTRL-W for Help------

If you press RETURN or type c or C to select the Compile option, INFORMIX-4GL displays the COMPILE MODULE Menu:
COMPILE MODULE: Object Runable Exit Create object file (.4go suffix). -------------------------------------------------Press CTRL-W for Help------

The Object option creates a le with a .4go extension. The Runable option creates a le with a .4gi extension. Select the Runable option if the current program module is a stand-alone 4GL program. If this is not the case, (that is, if the le is one of several 4GL source-code modules within a multi-module program), then you should use the Object option instead, and you must use the PROGRAM Design Menu to specify all the component modules.

Compiling 4GL Source Files

1-39

The MODULE Design Menu

After you select Object or Runable, a message near the bottom of the screen will advise you if INFORMIX-4GL issues a compile-time warning or error. If there are warnings (but no errors), a p-code le is produced. Select the Exit option of the next menu, and then Save-and-exit at the MODIFY MODULE Menu, if you want to save the p-code le without reading the warnings. Alternatively, you can examine the warning messages by selecting Correct at the next menu. When you nish editing the .err le that contains the warnings, you must select Compile again from the MODIFY MODULE Menu, since the Correct option deletes the p-code le. If there are compilation errors, the following menu appears:
COMPILE MODULE: Correct Exit Correct errors in the 4GL module. -------------------------------------------------Press CTRL-W for Help------

If you choose to correct the errors, an editing session begins on a copy of your source module with embedded error messages. (You do not need to delete error messages, since INFORMIX-4GL does this for you.) Correct your source le, save your changes, and exit from the editor. The MODIFY MODULE Menu reappears, prompting you to recompile, or to save or discard your changes without compiling. If there are no compilation errors, the MODIFY MODULE Menu appears with the Save-and-Exit option highlighted. If you select this option, INFORMIX-4GL saves the current source-code module as a disk le with the lename extension .4gl, and saves the compiled version as a le with the same lename, but with the extension .4go or .4gi. If you select the Discard-and-Exit option, INFORMIX-4GL discards any changes made to your le since you selected the Modify option.

1-40

Compiling 4GL Source Files

The MODULE Design Menu

The New Option

Select this option to create a new 4GL source-code module.
MODULE: Modify New Compile Program_Compile Create a new 4GL program module. Run Debug Exit

-------------------------------------------------Press CTRL-W for Help------

This option resembles the Modify option, but NEW MODULE is the menu title, and you must enter a new module name, rather than select it from a list. If you have not designated an editor previously in this session or with DBEDIT, you are prompted for an editor. Then an editing session begins.

The Compile Option

The Compile option enables you to compile an individual 4GL source-code module without rst selecting the Modify option.
MODULE: Modify New Compile Program_Compile Compile an existing 4GL program module. Run Debug Exit

-------------------------------------------------Press CTRL-W for Help------

After you specify the name of a 4GL source-code module to compile, the screen displays the COMPILE MODULE Menu. Its Object, Runable, and Exit options were described two pages earlier in the discussion of the Modify option.

The Program_Compile Option

The Program_Compile option of the MODULE Design Menu is the same as the Compile option of the PROGRAM Design Menu (see that option for details). It permits you to compile and combine modules as described in the
Compiling 4GL Source Files 1-41

The MODULE Design Menu

program specication database, taking into account the time when the modules were last updated. This option is useful when you have just modied a single module of a complex program and want to test it by compiling it with the other modules.

The Run Option

Select this option to begin execution of a compiled program.
MODULE: Modify New Compile Program_Compile Run Debug Exit Execute an existing 4GL program module or application program. -------------------------------------------------Press CTRL-W for Help------

The RUN PROGRAM screen presents a list of compiled modules and programs, with the highlight on the module corresponding to the current le, if any has been specied. Compiled programs must have the extension .4gi to be included in the list. If you compile a module with the extension .4go, you can run it by typing the lename and extension at the prompt. If no compiled programs exist, INFORMIX-4GL displays an error message and restores the MODULE Design Menu.

The Debug Option

Select this option to use the INFORMIX-4GL Interactive Debugger to analyze a program. This option is implemented only if you have separately purchased and installed the INFORMIX-4GL Interactive Debugger on your system.
MODULE: Modify New Compile Program_Compile Returns to the INFORMIX-4GL Menu. Run Debug Exit

-------------------------------------------------Press CTRL-W for Help------

1-42

Compiling 4GL Source Files

The FORM Design Menu

If you have the Debugger product, refer to the INFORMIX-4GL Interactive Debugger documentation for more information about this option.

The Exit Option

Select this option to exit from the MODULE Design Menu and display the INFORMIX-4GL Menu.
MODULE: Modify New Compile Program_Compile Returns to the INFORMIX-4GL Menu. Run Debug Exit

-------------------------------------------------Press CTRL-W for Help------

The FORM Design Menu

You can type f or F at the INFORMIX-4GL Menu to select the Form option. This option replaces the INFORMIX-4GL Menu with a new menu, called the FORM Design Menu:
FORM: Modify Generate New Compile Exit Change an existing form specification. -------------------------------------------------Press CTRL-W for Help------

You can use this menu to create, modify, and compile screen form specications. These specications dene visual displays that 4GL applications can use to query and modify the information in a database. INFORMIX-4GL screen form specications are ASCII les that are described in Chapter 4 of this manual, and in Chapters 6, 7, and 11 of the INFORMIX-4GL User Guide. The FORM Design Menu supports the following options: Modify Generate Change an existing 4GL screen form specication. Create a default 4GL screen form specication.
Compiling 4GL Source Files 1-43

The FORM Design Menu

New Compile Exit

Create a new 4GL screen form specication. Compile an existing 4GL screen form specication. Return to the INFORMIX-4GL Menu.

Readers familiar with the menu system of INFORMIX-SQL may notice that this menu resembles the menu displayed by the Form option of the INFORMIX-SQL Main Menu. Chapter 4 of this manual and Chapters 6 and 7 of the INFORMIX-4GL User Guide describe the usage and statement syntax of 4GL screen form specications.

The Modify Option

The Modify option of the FORM Design Menu enables you to edit an existing form specication le. It resembles the Modify option in the MODULE Design Menu, since both options are used to edit program modules.
FORM: Modify Generate New Compile Exit Change an existing form specification. -------------------------------------------------Press CTRL-W for Help------

If you select this option, you are prompted to select the name of a form specication le to modify. Source les created at the FORM Design Menu (or at the command line by the FORM4GL screen form facility) have the le extension .per.

1-44

Compiling 4GL Source Files

The FORM Design Menu

If you have not already designated a text editor in this INFORMIX-4GL session or with DBEDIT, you are prompted for the name of an editor. Then an editing session begins, with the form specication source-code le that you specied as the current le. When you leave the editor, INFORMIX-4GL displays the MODIFY FORM Menu with the Compile option highlighted.
MODIFY FORM: Compile Save-and-exit Compile the form specification. Discard-and-exit

-------------------------------------------------Press CTRL-W for Help------

Now you can press RETURN to compile the revised form specication le. If the compiler nds errors, the COMPILE FORM Menu appears:
COMPILE FORM: Correct Exit Correct errors in the form specification. -------------------------------------------------Press CTRL-W for Help------

Press RETURN to select Correct as your option. An editing session begins on a copy of the current form, with diagnostic error messages embedded where the compiler detected errors. INFORMIX-4GL deletes these messages when you save and exit from the editor. After you correct the errors, the MODIFY FORM Menu appears again, with the Compile option highlighted. Press RETURN to recompile. If there are no compilation errors, you are prompted whether to save the modied form specication le and the compiled form, or to discard the changes. (Discarding the changes restores the version of your form specications from before you chose the Modify option.)

Compiling 4GL Source Files

1-45

The FORM Design Menu

The Generate Option

You can type g or G to select the Generate option. This option creates a simple default screen form for use directly in your 4GL program, or for you to edit later by selecting the Modify option.
FORM: Modify Generate New Compile Exit Generate and compile a default form specification. -------------------------------------------------Press CTRL-W for Help------

When you select this option, INFORMIX-4GL prompts you to select a database, to choose a lename for the form specication, and to identify the tables that the form will access. After you provide this information, INFORMIX-4GL creates and compiles a form specication le. (This is equivalent to running the -d (default) option of FORM4GL, as described near the end of Chapter 4, Form Building and Compiling.)

The New Option

The New option of the FORM Design Menu enables you to create a new screen form specication.
FORM: Modify Generate New Compile Create a new form specification. Exit

-------------------------------------------------Press CTRL-W for Help------

After prompting you for the name of your form specication le, INFORMIX-4GL places you in the editor where you can create a form specication le. When you leave the editor, INFORMIX-4GL transfers you to the NEW FORM Menu that is like the MODIFY FORM Menu. You can compile your form and correct it in the same way.

1-46

Compiling 4GL Source Files

The FORM Design Menu

The Compile Option

The Compile option enables you to compile an existing form specication le without going through the Modify option.
FORM: Modify Generate New Compile Exit Compile an existing form specification. -------------------------------------------------Press CTRL-W for Help------

INFORMIX-4GL prompts you for the name of the form specication le and then performs the compilation. If the compilation is not successful, INFORMIX-4GL displays the COMPILE FORM Menu with the highlight on the Correct option.

The Exit Option

The Exit option clears the FORM Design Menu from the screen.
FORM: Modify Generate New Compile Returns to the INFORMIX-4GL Menu. Exit

-------------------------------------------------Press CTRL-W for Help------

Selecting this option restores the INFORMIX-4GL Menu:

INFORMIX-4GL: Module Form Program Query-language Exit Create, modify or run individual 4GL program modules. -------------------------------------------------Press CTRL-W for Help------

Compiling 4GL Source Files

1-47

The PROGRAM Design Menu

The PROGRAM Design Menu

An INFORMIX-4GL program can be a single source-code module that you create and compile at the MODULE Design Menu. For applications of greater complexity, however, it is often easier to develop and maintain an INFORMIX-4GL program that includes several modules. The INFORMIX-4GL Menu includes the Program option so that you can create multiple-module programs. When you select this option, INFORMIX-4GL searches your DBPATH directories (see Appendix C) for the program specication database, called syspgm4gl. This database describes the runner options and the modules of your program. If INFORMIX-4GL cannot nd this database, you are asked if you want one created. If you enter y in response, INFORMIX-4GL creates the syspgm4gl database, grants CONNECT privilege to PUBLIC, and displays the PROGRAM Design Menu. As Database Administrator of syspgm4gl, you can later restrict the access of other users. If syspgm4gl already exists, the PROGRAM Design Menu appears.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Change the compilation definition of a 4GL application program. Exit

-------------------------------------------------Press CTRL-W for Help------

You can use this menu to create or modify a multi-module 4GL program specication, to compile a program, or to execute or analyze a program. The PROGRAM Design Menu supports the following eight options: Modify New Compile Planned_Compile Run Debug Undene Exit
1-48 Compiling 4GL Source Files

Change an existing program specication. Create a new program specication. Compile an existing program. Display the steps to compile an existing program. Execute an existing program. Invoke the INFORMIX-4GL Interactive Debugger. Delete an existing program specication. Return to the INFORMIX-4GL Menu.

The PROGRAM Design Menu

You must rst use the MODULE Design Menu and FORM Design Menu to enter and edit the INFORMIX-4GL statements within the component source-code modules of a 4GL program. Then you can use the PROGRAM Design Menu to identify which modules are part of the same application program, and to combine all the 4GL modules in an executable program.

The Modify Option

The Modify option enables you to modify the specication of an existing 4GL program. (This option is not valid unless at least one program has already been specied. If none has, you can create a program specication by selecting the New option from the same menu.) INFORMIX-4GL prompts you for the name of the program specication you want to modify. It then displays a screen and menu that you can use to update the information in the program specication database, as shown in Figure 1-3:
MODIFY PROGRAM: 4GL Globals Edit the 4GL sources list. Other Program_Runner Rename Exit

-------------------------------------------------Press CTRL-W for Help-----Program [myprog ] Runner [fglgo ] Runner Path [ ] Debugger [fgldb ] Debugger Path [ ] 4gl Source [main [funct [rept [ [ 4gl Source Path [/u/john/appl/4GL [/u/john/appl/4GL [/u/john/appl/4GL [ [ Global Source Path [ [ Other .4go Path [ [

] ] ] ] ]

] ] ] ] ]

Global Source [ ] [ ] Other .4go [obj ] [ ]

] ]

] ]

Figure 1-3

Example of a Program Specication Entry

The name of the program appears in the Program eld. In Figure 1-3 this name is myprog. You can change the name by selecting the Rename option. The program name, with extension .4gi, is assigned to the program produced by compiling and combining all the source les. (Compiling and combining is done by the Compile option, as described later in this chapter, or by the Program_Compile option of the MODULE Design Menu.) In this case, the runable program would have the name myprog.4gi.
Compiling 4GL Source Files 1-49

The PROGRAM Design Menu

The 4GL option enables you to update the entries for 4gl Source and 4gl Source Path. The ve rows of elds under these labels form a screen array. If you select the 4GL option, INFORMIX-4GL executes an INPUT ARRAY statement so you can move through the array and scroll for up to a maximum of 100 entries. The INPUT ARRAY statement description in Chapter 7 explains how to use function keys to scroll, delete rows, and insert new rows. (You cannot redene function keys, however, as you can with an INFORMIX-4GL program.) In the example shown in Figure 1-3, the 4GL source program has been broken into three modules: a module containing the MAIN program block (main.4gl), a module containing functions (funct.4gl), and a module containing REPORT statements (rept.4gl). These modules are all located in the directory /u/john/appl/4GL. If a module contains only global variables, you can list it here or in the Global Source array. The Globals option enables you to update the Global Source array. If you use the Global Source array to store a globals module, any modication of the globals module le causes all 4GL modules to be recompiled when you select the Compile option. The Other option enables you to update the entries for the Other .4go and Other .4go Path elds. This is where you specify the name and location of other 4GL object les (.4go les) to include in your program. Do not specify the lename extensions. You can list up to 100 les in this array. The Program_Runner option enables you to specify the name and location of the p-code runner to execute your program. You can run INFORMIX-4GL programs with fglgo (the default) or with a customized p-code runner. A customized p-code runner is an executable program that you create to run 4GL programs that call C functions, as described later in this chapter. If you do not modify the Runner eld, your program is executed by fglgo when you select the Run option from the PROGRAM Design Menu. The MODIFY PROGRAM screen form contains two additional elds labeled Debugger and Debugger Path. If you have the INFORMIX-4GL Interactive Debugger, you can also use the Program_Runner option to enter the name of a customized Debugger. See the section RDS Programs That Call C Functions later in this chapter for information about the use of a customized Debugger. For the procedures to create a customized Debugger, refer to Appendix C of the Guide to the INFORMIX-4GL Interactive Debugger, which includes an example. The Exit option of the MODIFY PROGRAM Menu returns you to the PROGRAM Design Menu.
1-50 Compiling 4GL Source Files

The PROGRAM Design Menu

The New Option

The New option of the PROGRAM Design Menu enables you to create a new specication of the program modules and libraries that make up the desired application program.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Add the compilation definition of a 4GL application program. Exit

-------------------------------------------------Press CTRL-W for Help------

The New option is identical to the Modify option, except that you must rst supply a name for your program. INFORMIX-4GL then displays a blank form with a NEW PROGRAM Menu that has the same options as the MODIFY PROGRAM Menu.

The Compile Option

The Compile option compiles and combines the modules listed in the program specication database, taking into account the time when les were last updated. INFORMIX-4GL compiles only those les that have been modied since they were last compiled, except in the case where you have modied a module listed in the Global Source array. If you have modied a module that is listed in the Global Source array, all les are recompiled.
PROGRAM: Modify New Compile Planned_Compile Compile a 4GL application program. Run Debug Undefine Exit

-------------------------------------------------Press CTRL-W for Help------

The Compile option produces a runable p-code le with a .4gi extension. INFORMIX-4GL lists each step of the compilation as it occurs.

Compiling 4GL Source Files

1-51

The PROGRAM Design Menu

The Planned_Compile Option

Taking into account the time of last change for the various les in the dependency relationships, the Planned_Compile option prompts for a program name and displays a summary of the steps that will be executed if you select Compile. No compilation actually takes place.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Show the planned compile actions of a 4GL application program. Exit

-------------------------------------------------Press CTRL-W for Help-----Compiling INFORMIX-4GL sources: /u/john/appl/4GL/main.4gl /u/john/appl/4GL/funct.4gl /u/john/appl/4GL/rept.4gl Linking other objects: /u/john/appl/Com/obj.4go

If you have made changes in all the components of the program listed in Figure 1-3 since the last time they were compiled, INFORMIX-4GL displays the previous screen.

The Run Option

Select the Run option to execute a compiled program.
PROGRAM: Modify New Compile Planned_Compile Run Debug Execute a 4GL application program Undefine Exit

-------------------------------------------------Press CTRL-W for Help------

The screen lists any compiled programs (les with the extension .4gi) and highlights the current program, if one has been specied. This option resembles the Run option of the MODULE Design Menu. Although .4go les are not displayed, you can also enter the name and extension of a .4go le. Whatever compiled program you select is executed by fglgo, or by the runner that you specied in the Runner eld of the Program Specication screen. This screen was illustrated earlier, in the description of the MODIFY PROGRAM Menu.
1-52 Compiling 4GL Source Files

The PROGRAM Design Menu

The Debug Option

The Debug option works like the Run option but enables you to examine a 4GL program with the INFORMIX-4GL Interactive Debugger. This option is not implemented unless you have purchased the Debugger.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Drop the compilation definition of a 4GL application program. Exit

-------------------------------------------------Press CTRL-W for Help------

The Undene Option

The Undene option of the PROGRAM Design Menu prompts you for a program name and removes the compilation denition of that program from the syspgm4gl database. This action removes the denition only. Your program and 4GL modules are not removed.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Drop the compilation definition of a 4GL application program. Exit

-------------------------------------------------Press CTRL-W for Help------

The Exit Option

The Exit option clears the PROGRAM Design Menu from the screen and restores the INFORMIX-4GL Menu.

Compiling 4GL Source Files

1-53

The QUERY LANGUAGE Menu

The QUERY LANGUAGE Menu

The SQL interactive interface is identical to the interactive SQL interface of INFORMIX-SQL. You can use this option only if you have separately purchased and installed INFORMIX-SQL on your system. The Query-language option is placed at the top-level menu so you can test SQL statements without leaving the INFORMIX-4GL Programmers Environment. You can also use this option to create, execute, and save SQL scripts.

Creating Executable RDS Programs

To create an INFORMIX-4GL application with the INFORMIX-4GL Rapid Development System requires the following steps: 1. Create or modify a .4gl source le. 2. Compile the source le into a .4go p-code le. 3. Combine multiple .4go modules into a single .4gi le. 4. Invoke the INFORMIX-4GL runner, specifying a 4GL program. Step 3 is not required if your program has only one module. The sections that follow describe how to carry out these steps, both from the Programmers Environment and at the system prompt. Subsequent sections of this chapter describe how to use the INFORMIX-4GL Rapid Development System to compile and execute 4GL programs that call C functions. (These special Rapid Development System procedures require a C language compiler and linker, which are unnecessary for 4GL applications that do not call programmer-dened C functions.)

Working in the RDS Programmers Environment

If your software has been installed according to the instructions in your Installation Guide, you can enter r4gl at the system prompt to invoke the Programmers Environment. After a sign-on message, the INFORMIX-4GL Menu appears.

1-54

Compiling 4GL Source Files

Working in the RDS Programmers Environment

Creating a New Source Module

This section outlines the procedure for creating a new module. If your source module already exists but needs to be modied, skip ahead to the next section, Revising an Existing Module.

Press RETURN at the INFORMIX-4GL Menu to select the Module option.

The screen displays the MODULE Design Menu.

If you are creating a new .4gl source module, press n to select the New
option of the MODULE Design Menu. The screen prompts you for a name to assign to the new module.

Enter a name for the new module. The name must begin with a letter, and
can include letters, numbers, and underscores. The name must be unique among the les in the same directory, and among the other program modules, if it will be part of a multi-module program. INFORMIX-4GL attaches extension .4gl to this identier, as the lename of your new source module.

Revising an Existing Module

If you are revising an existing 4GL source le, rather than creating a new one, the procedures to begin an editing session are slightly different from the steps that were just described.

Select the Modify option of the MODULE Design Menu. The screen lists the names of all the .4gl source modules in the current
directory and prompts you to select a source le to edit. Use the Arrow keys to highlight the name of a source module and press RETURN, or enter a lename (with no extension). If you specied an editor with the DBEDIT environment variable, an editing session begins automatically. Otherwise, the screen prompts you to specify a text editor.

Specify the name of a text editor, or press RETURN for vi, the default editor. Now you can begin an editing session by entering 4GL statements. (The chapters that follow describe INFORMIX-4GL statements and programs.)

When you have nished entering or editing your 4GL code, use an appropriate editor command to save your source le and end the text editing session.

Compiling 4GL Source Files

1-55

Working in the RDS Programmers Environment

Compiling a Source Module

The .4gl source le module that you create or modify is an ASCII le that must be compiled before it can be executed. After you save your le and exit from the editor, the screen prompts you to choose among Compile, Save-and-exit, or Discard-and-exit options.

Select the Compile option to compile the module. After you select
Compile, the screen prompts you to select among Object, Runable, and Exit options. What you should do depends on whether your module is a complete program, or whether it is one of several .4gl modules that together comprise a complete program.

If the module is a complete 4GL program that requires no other modules,

select Runable. This option creates a compiled p-code version of your program module, with the same lename, but with extension .4gi.

If the module is one module of a multi-module 4GL program, select

Object. This creates a compiled p-code version of your program module, with the same lename, but with extension .4go. See also the procedures for combining program modules, which are described later in this section. If the compiler detects errors after either option, no compiled le is created, and the screen prompts you to select Correct or Exit. Follow the rst two steps on the next page after an error.

Select Correct to resume the previous text editing session, with the
same 4GL source code, but with error messages in the le.

Edit the le to correct the error, and select Compile again. If an error
message appears, repeat the previous steps, until the module compiles without error.

After the module compiles successfully, the screen prompts you again to
Compile, or to Save-and-exit, or to Discard-and-exit. Select the second option to save the compiled program. The MODULE Design Menu appears again on your screen.

If your program requires screen forms, you must select Exit to return to the
INFORMIX-4GL Menu and then select Form to display the FORM Design

Menu. See Chapter 4 for information about designing and creating screen forms.

If your program displays help messages, you must create a help le and
compile it with the mkmessage utility. See Chapter 8 of the INFORMIX4GL User Guide for more information about implementing help messages in INFORMIX-4GL programs.

1-56

Compiling 4GL Source Files

Working in the RDS Programmers Environment

Combining Program Modules

If the module that you compiled is the only module in your program, you are now ready to run your program, and you can skip the steps that are described here. If your new or modied module is part of a multi-module 4GL program, however, you must combine all of the modules into a single program le before you can run the program.

If you are not at the INFORMIX-4GL Menu, select Exit until that menu
appears. Then select the Program option to display the PROGRAM Design Menu.

Select the New option if you are creating a new multi-module 4GL
program, or select Modify if you are modifying an existing one. In either case, the screen prompts you for the name of a program.

Enter the name (without a le extension) of the program that you are
modifying, or the name to be assigned to a new program. Names must begin with a letter, and can include letters, underscores ( _ ), and numbers. After you enter a valid name, the PROGRAM screen appears, with your program name in the rst eld. If you selected Modify, the names and pathnames of the source-code modules are also displayed. The PROGRAM screen appears below the MODIFY PROGRAM Menu, rather than below the NEW PROGRAM Menu. (Both menus list the same options.)

NEW PROGRAM: 4GL Globals Edit the 4GL sources list.

Other

Program_Runner

Rename

Exit

----------------------------------------------- Press CTRL-W for Help ------Program [ ] Runner [fglgo ] Runner Path [ ] Debugger[fgldb ] Debugger Path [ ] 4gl Source [ ] [ ] [ ] [ ] [ ] 4gl Source Path [ [ [ [ [

] ] ] ] ]

Global Source Global Source Path [ ] [ [ ] [ Other .4go [ ] [ ] Other .4go Path [ [

] ]

] ]

Compiling 4GL Source Files

1-57

Working in the RDS Programmers Environment

To specify new 4GL modules or edit the list of 4GL modules, press
RETURN to select the 4GL option. You can enter or edit the name of a module, without the .4gl le extension. Repeat this step for every module. If the module is not in the current directory or in a directory specied by the DBPATH environment variable, enter the pathname to the directory where the module resides.

The name of the runner (and of the Debugger, if you have the INFORMIX-4GL Interactive Debugger) are usually as illustrated in the PROGRAM screen, unless your 4GL program calls C functions. A later sec-

tion of this chapter, RDS Programs That Call C Functions, explains how to create a customized runner or Debugger, which you can then specify by selecting the Program_Runner option.

To enter or edit the name or pathname of a Globals module, select the

Globals option and provide the corresponding information.

If your program includes any .4go modules that you have already compiled, you can select the Other option to enter or edit their lenames and pathnames.

After you correctly list all of the modules of your 4GL program, select the
Exit option to return to the PROGRAM Design Menu.

Select the Compile option of the PROGRAM Design Menu. This produces
a le that combines all of your .4gl source les into an executable program. Its lename is the program name that you specied, with extension .4gi. The screen lists the names of your .4gl source modules and displays the PROGRAM Design Menu with the Run option highlighted. See also the section Program Filename Extensions (C Compiler Version) later in this chapter for information about the backup les that are produced automatically when you work at the Programmers Environment of the INFORMIX-4GL Rapid Development System.

Executing a Compiled RDS Program

You can type r or press RETURN to select the Run option. This option executes the compiled 4GL program. Menus, screen forms, windows, or other screen output are displayed, according to your program logic and your keyboard interaction with the program.

1-58

Compiling 4GL Source Files

Working at the RDS Command Line

Invoking the Debugger

If you are developing or modifying an INFORMIX-4GL program, you have much greater control over program execution by rst invoking the INFORMIX-4GL Interactive Debugger. If you have purchased the Debugger, you can invoke it from the MODULE Design Menu or PROGRAM Design Menu of the Programmers Environment by selecting the Debug option. See the Guide to the INFORMIX-4GL Interactive Debugger for detailed information on the use of the Debugger as a programmers productivity tool.

Working at the RDS Command Line

You can create the same .4gl source les and compiled .4go and .4gi p-code les at the operating system prompt. Figure 1-4 shows the process of creating, compiling, and running or debugging a single-module program from the command line.

Compiling 4GL Source Files

1-59

Working at the RDS Command Line

TEXT EDITOR

.4gl Source File

P-CODE COMPILER fglpc .4go Compiled p-code File P-CODE RUNNER fglgo
Figure 1-4 Creating and Running a Single-Module Program

DEBUGGER fgldb

Here the rectangles represent processes controlled by specic commands, and the circles represent les. Arrows indicate whether a le serves as input or output for a process. This diagram is simplied and ignores the similar processes by which forms, help messages, and any other components of INFORMIX-4GL applications are compiled and executed.

The cycle begins in the upper left corner with a text editor, such as vi,
to produce a 4GL source module.

The program module can then be compiled, using the fglpc p-code
compiler. (If error messages are produced by the compiler, nd them in the .err le, and edit the .4gl le to correct the errors. Then recompile the corrected .4gl le.)

1-60

Compiling 4GL Source Files

Working at the RDS Command Line

The following command line invokes the p-code runner:

fglgo lename where lename species a compiled 4GL le to be executed. Executing a program that is undergoing development or modication sometimes reveals the existence of run-time errors. If you have the INFORMIX-4GL Interactive Debugger, you can invoke it to analyze and identify run-time errors in your program by entering the command: fgldb lename where lename species your compiled 4GL le. You can then recompile and retest the program. When it is ready for use by others, they can use the fglgo runner to execute the compiled program. A correspondence between commands and menu options of the RDS Programmers Environment is summarized by the following list:
Command

vi fglpc fglgo fgldb

Invokes UNIX System Editor 4GL P-Code Compiler 4GL P-Code Runner 4GL Interactive Debugger

Menu Option Module New/Modify Compile Run Debug

Creating or Modifying a 4GL Source File

Use your system editor or another text-editing program to create a .4gl source le, or to modify an existing le. See the documentation of your text editor and the other chapters of this manual for details.

Compiling an RDS Source File

You cannot execute a 4GL program until you have compiled each source module into a .4go le. Do this at the system prompt by entering the fglpc command, which compiles your 4GL source code, and generates a le containing tables of information and blocks of p-code. You can then run this compiled code by using the INFORMIX-4GL p-code runner (or the INFORMIX-4GL Interactive Debugger, if you have the Debugger). The INFORMIX-4GL source-code module to be compiled should have the le extension .4gl. The syntax of a fglpc command line follows:

Syntax
fglpc { -V | [ -ansi ] [ -a ] [ -p pathname ] source [ .4gl ] . . . }

Compiling 4GL Source Files

1-61

Working at the RDS Command Line

Explanation
-V -ansi -a -p pathname source.4gl displays the version number of the software. instructs the compiler to check all SQL statements for compliance with ANSI standards. causes your compiled program to check array bounds at run time. stores object (.4go) les and error (.err) les in the directory specied by pathname. is the name of an INFORMIX-4GL source-code module.

Notes
1. The fglpc command reads source.4gl les and creates a compiled version of each, with the lename source.4go. You can specify any number of source les, in any order, with or without their .4gl lename extensions. 2. If you specify the -V option, the screen displays the version number of your SQL and p-code compiler software. Any other command options are ignored. After displaying this information, the program terminates without compiling. 3. If you specify the -ansi option, it must appear rst in your list of fglpc command arguments. The -ansi option asks for compile-time warning messages if your source code includes Informix extensions to the ANSI standard for SQL. (Chapter 7 lists the Informix syntax extensions.) 4. If an error or warning occurs during compilation, INFORMIX-4GL creates a le called source.err. Look in source.err to nd where the error or warning occurred in your code. 5. You can use the -p pathname option to specify a non-default directory for the .4go and .err les. Otherwise, any les produced by fglpc are stored in your current working directory. 6. Since the -a option requires additional processing, you may want to use this option only for debugging during development.

Examples
The following command compiles a 4GL source le single.4gl, and creates a le called single.4go in the current directory: fglpc single.4gl The next command line compiles two 4GL source les: fglpc -p /u/ken fileone filetwo
1-62 Compiling 4GL Source Files

Working at the RDS Command Line

This command generates two compiled les, leone.4go and letwo.4go, and stores them in subdirectory /u/ken. Any compiler error messages are saved in les leone.err or letwo.err in the same directory.

Concatenating Multi-Module Programs

If a program has several modules, the compiled modules must all be concatenated into a single le, as represented in Figure 1-5:

TEXT EDITOR

.4gl Source Files

P-CODE COMPILER fglpc .4go p-code Object Files CONCATENATION UTILITY .4gi p-code Executable Files P-CODE RUNNER fglgo
Figure 1-5 Creating and Running a Multi-Module Program Compiling 4GL Source Files 1-63

Working at the RDS Command Line

The UNIX cat command combines the listed les into the le specied after the redirect symbol (>) in a command line of the form
cat file1.4go file2.4go ... fileN.4go > new.4gi

which combines a list of .4go les into a le called new.4gi. Note: The new lename of the combined le must have either a .4go or a .4gi extension. Throughout this manual, extension .4gi designates runable les that have been compiled (and concatenated, if several source modules comprise the program). You may wish to follow this convention in naming les, since only .4gi les are displayed from within the Programmers Environment. This convention is also a convenient way to distinguish complete program les from object les that are individual modules of a multi-module program. If your 4GL program calls C functions or INFORMIX-ESQL/C functions, you must follow procedures that are described in the section RDS Programs That Call C Functions before you can run your application.

Running RDS Programs

To execute a compiled 4GL program from the command line, you can invoke the p-code runner, fglgo. Its syntax follows:

Syntax
fglgo { -V | [ -a ] lename[.4go|.4gi ] [ args ] }

Explanation:
-V displays the SQL version number and the p-code version number. After displaying this information, the program quits without invoking the p-code runner. causes array bounds checking at run time. is the name of a compiled 4GL le. The lename must have a .4go or .4gi extension. You do not need to enter this extension on the command line. are any arguments required by your 4GL program.

-a lename

args

1-64

Compiling 4GL Source Files

Working at the RDS Command Line

Notes
1. If you do not specify a lename extension in the command line, fglgo looks rst for the lename with a .4gi extension, and then for the lename with a .4go extension. 2. To run a 4GL program that calls programmer-dened C functions, you cannot use fglgo. You must instead use a customized p-code runner. The section RDS Programs That Call C Functions describes how to create a customized runner.

Examples
To run a compiled program named myprog.4go, enter the following command line at the operating system prompt:
fglgo myprog

or
fglgo myprog.4go

Running Multi-Module Programs

To run a program with multiple modules, you must compile each module and then combine them by an operating system concatenation utility, as described in an earlier section. For example, if mod1.4go, mod2.4go, and mod3.4go are compiled INFORMIX-4GL modules that you want to run as one program, you must rst combine them as in the following example:
cat mod1.4go mod2.4go mod3.4go > mods.4gi

You can then run the mods.4gi program by using the command lines:
fglgo mods

or
fglgo mods.4gi

Running Programs with the Interactive Debugger

You can also run compiled 4GL programs with the INFORMIX-4GL Interactive Debugger. This 4GL source-code debugger is a p-code runner with a rich command set for analyzing 4GL programs. You can use the Debugger to locate logical and run-time errors in your 4GL programs and to become more familiar with 4GL programs. The Debugger must be purchased separately from INFORMIX-4GL.

Compiling 4GL Source Files

1-65

Working at the RDS Command Line

If you have the Debugger, you can invoke it at the system prompt by a command line of the form:
fgldb lename

Here lename is any runable 4GL le that you produced by an fglpc command. See Chapter 8 of the Guide to the INFORMIX-4GL Interactive Debugger for the complete syntax of the fgldb command.

RDS Programs That Call C Functions

If your INFORMIX-4GL Rapid Development System program calls programmer-dened C functions, you must create a customized runner to execute the program. You can do this by following two steps: 1. Edit a structure denition le to contain information about your C functions. This le is named fgiusr.c and is supplied with INFORMIX-4GL. 2. Compile and link the fgiusr.c le with the les that contain your C functions. To do this, use the cfglgo command. You can then use the runner produced by the cfglgo command to run the 4GL program that calls your C functions. Both the fgiusr.c le and the cfglgo command are described in the pages that follow. Note: To create a customized runner, you must have a C compiler installed on your system. You do not need a C compiler, however, and you do not need to follow the procedures described in this section, if the only functions that your INFORMIX-4GL Rapid Development System program calls are INFORMIX-4GL or INFORMIX-ESQL/C library functions, or functions written in the INFORMIX-4GL language.

1-66

Compiling 4GL Source Files

Working at the RDS Command Line

Editing the fgiusr.c File

With your INFORMIX-4GL software, you receive a le named fgiusr.c. This le is located in the etc subdirectory of the directory in which you install INFORMIX-4GL (that is, in INFORMIXDIR/etc). The following listing shows the fgiusr.c le in its unedited form:
/********************************************************** * * * INFORMIX SOFTWARE, INC. * * * * Title: fgiusr.c * * Sccsid: @(#)fgiusr.c 4.2 8/26/87 10:48:37 * * Description: * * definition of user C functions * * * *********************************************************** */ /******************************************************* * This table is for user-defined C functions. * * Each initializer has the form: * * "name", name, nargs * * Variable # of arguments: * * set nargs to -(maximum # args) * * Be sure to declare name before the table and to leave the * line of 0s at the end of the table. * * Example: * * You want to call your C function named "mycfunc" and it expects * 2 arguments. You must declare it: * * int mycfunc(); * * and then insert an initializer for it in the table: * * "mycfunc", mycfunc, 2 ********************************************************* */ #include "fgicfunc.h" cfunc_t usrcfuncs[] = { 0, 0, 0 };

The fgiusr.c le is a C language le that you can edit to declare any number of programmer-dened C functions.

Compiling 4GL Source Files

1-67

Working at the RDS Command Line

To edit fgiusr.c, you can copy the le to any directory. (Unless this is your working directory at compile time, you must specify the full pathname of the edited fgiusr.c le when you compile.) Edit fgiusr.c to specify the following:

A declaration for each function:

int function-name( ); Three initializers for each function:
" function-name ", function-name, [ - ] integer,

The symbols ( ) ; must follow function-name in the declaration. The rst initializer is a character pointer (the function name between double quotation marks). The second is a function pointer (the name without quotes). The third is an integer (for the number of arguments expected by the function). If the number of arguments expected by the function can vary, make the third argument the maximum number of arguments, prexed with a minus ( - ) sign. You must use commas ( , ) to separate the three initializers. Insert a set of initializers for each C function that you declare. A line of three zeroes indicates the end of the structure. Here is an example of an edited fgiusr.c le: #include "fgicfunc.h" int function-name(); cfunc_t usrcfuncs[] = { " function-name",function-name,1, 0,0,0 } Here the 4GL program will be able to call a single C function called function-name that has one ( 1 ) argument. If you have several 4GL programs that call C functions, you can use fgiusr.c in either of two ways:

You can create one customized p-code runner. In this case, you can edit
fgiusr.c to specify all the C functions called from all your 4GL programs. After you create one comprehensive runner, you can use it to execute all your 4GL applications.

You can create several application-specic runners. In this case, you can
either make a copy of the fgiusr.c le (with a new name) for each custom1-68 Compiling 4GL Source Files

Working at the RDS Command Line

ized runner, or you can re-edit fgiusr.c to contain information on the C functions for a specic application before you compile and link. If you create several runners, you must know which customized runner to use with each 4GL application. In some situations the rst method is more convenient, since users do not have to keep track of which runner supports each 4GL application.

Creating a Customized Runner

You can use the cfglgo command to create a customized runner. You can use cfglgo to compile C modules and INFORMIX-ESQL/C modules that contain functions declared in an edited fgiusr.c le.

Syntax
cfglgo { -V | fgiusr.c cle. { ec | c | o } [ . . . ] [ -o newfglgo ] }

Explanation
-V fgiusr.c cle displays the version number of the software. is the name of the le that you edited to declare C and/or
INFORMIX-ESQL/C functions.

is the name of a source le containing INFORMIX-ESQL/C or C functions to be compiled and linked with the new runner; or the name of an object le previously compiled from a .c or .ec le. species the name of the customized runner.

-o newfglgo

Notes
1. The cfglgo command compiles and links the edited fgiusr.c le with your C program les into an executable program that can run your 4GL application. 2. You can rename an edited structure denition le. If you do so, specify its new lename in place of fgiusr.c. 3. If you do not specify the -o newfglgo option, the new runner is given the default name a.out. 4. You can specify any number of uncompiled or compiled C or INFORMIX-ESQL/C les in a cfglgo command line. 5. You must have the INFORMIX-ESQL/C product to compile INFORMIX-ESQL/C les with cfglgo.
Compiling 4GL Source Files 1-69

Working at the RDS Command Line

6. If the fgiusr.c le to be linked is not in the current directory, you must specify a full pathname. 7. The customized runner can also run 4GL programs that do not call C functions. 8. The -V option displays the release version numbers of your p-code and SQL software and returns the system prompt. All other arguments are ignored, and no other output is produced.

Examples
The following example 4GL program calls the C function prdate( ): prog.4gl:
main . . . call prdate() . . . end main

The function prdate( ) is dened in le cfunc.c, as shown here: cfunc.c:

#include <stdio.h> #include <time.h> prdate() { /* This program timestamps file FileX */ long cur_date; extern int errno; FILE *fptr; time(&cur_date); fptr = fopen("time_file","a"); fprintf(fptr,"FileX was accessed %s", ctime(&cur_date)); fclose(fptr); }

1-70

Compiling 4GL Source Files

Working at the RDS Command Line

The C function is declared and initialized in the following fgiusr.c le: fgiusr.c:
1 #include "fgicfunc.h" 2 3 int prdate(); 4 cfunc_t usrcfuncs[] = 5 { 6 "prdate", prdate, 0, 7 0, 0, 0 8 };

An explanation of this example of an fgiusr.c le follows: line 1: line 3: line 4: line 6: line 7: The le fgicfunc.h is always included. This line already exists in the unedited fgiusr.c le. This is the declaration of the function prdate( ). You must add this line to the le. This line already exists in the unedited le. It declares the structure array usrcfuncs. This line contains the initializers for function prdate( ). Since it expects no arguments, the third value is zero. The line of three zeros indicates that no more functions are to be included.

In this example, you can use the following commands to compile the 4GL program, to compile the new runner, and to run the program: To compile the example 4GL program:
fglpc prog.4gl

To compile the new runner:

cfglgo fgiusr.c cfunc.c -o newfglgo

To run the 4GL program:

newfglgo prog.4go

Compiling 4GL Source Files

1-71

RDS Program Filename Extensions

Running Programs That Call C Functions

After you create a customized runner, you can use it to execute any 4GL program whose C functions you correctly specied in the edited fgiusr.c le. The syntax of a customized runner (apart from its name) is the same as the syntax of fglgo, which was described in an earlier section of this chapter, Running RDS Programs. You can also create a customized Debugger to run a 4GL program that calls C functions. See Appendix C of the Guide to the INFORMIX-4GL Interactive Debugger for details and an example of how to create a customized Debugger. You cannot create a customized runner or a customized Debugger from the menus and screen forms of the Programmers Environment. You must exit to the system prompt and follow the procedures that were just described if you are developing a 4GL program that calls user-dened C functions. Then you can return to the Programmers Environment and use the Program_Runner option of the MODIFY PROGRAM Menu or NEW PROGRAM Menu to specify the name of a customized runner or Debugger.

RDS Program Filename Extensions

Source, runable, error, and backup les generated by INFORMIX-4GL are stored in the current directory and are labeled with a lename extension. The following list shows the le extensions for the source, runable, and error les. These les are produced during the normal course of using the INFORMIX-4GL Rapid Development System. le.4gl le.4go le.4gi le.err is an INFORMIX-4GL source le. is an INFORMIX-4GL le that has been compiled to p-code. is an INFORMIX-4GL le that has been compiled to p-code. is an INFORMIX-4GL source error le, created when an attempt to compile a module fails or produces a warning. The le contains the 4GL source code plus compiler syntax warnings or error messages. is an INFORMIX-4GL object error le, created when an attempt to compile or to link a non-INFORMIX-4GL source-code or object module fails. The le contains 4GL source code and annotated compiler errors.

le.erc

form.per is a FORM4GL source le. form.frm is a FORM4GL object le. form.err

1-72 Compiling 4GL Source Files

is a FORM4GL source error le.

RDS Program Filename Extensions

The last three les do not exist unless you create or modify a screen form specication le, as described in Chapter 4. The next page lists the corresponding le extensions for the backup les that INFORMIX-4GL automatically creates when you use the Programmers Environment to process 4GL source les. The following list identies backup les that are produced when you use INFORMIX-4GL from the Programmers Environment. le.4bl le.4bo le.4be le.pbr le.fbm is an INFORMIX-4GL source backup le, created during the modication and compilation of a .4gl program module. is an object backup le, created during the compilation of a .4go program module. is an object backup le, created during the compilation of a .4gi program module. is a FORM4GL source backup le. is a FORM4GL object backup le.

Under normal conditions, INFORMIX-4GL creates the backup les and intermediate les as necessary, and deletes them upon a successful compilation. If you interrupt a compilation, you may nd one or more of the les in your current directory. If you compile with a fglpc command line that includes the p pathname option, INFORMIX-4GL creates the .4gi, .4go, .err, and corresponding backup les in the directory specied by pathname, rather than in your current directory. During the compilation process, INFORMIX-4GL stores a backup copy of the le.4gl source le in le.4bl. The time stamp is modied on the (original) le.4gl source le, but not on the backup le.4bl le. In the event of a system crash, you may need to replace the modied le.4gl le with the backup copy contained in the le.4bl le. The Programmers Environment does not allow you to begin modifying a .4gl or .per source le if the corresponding backup le already exists in the same directory. After an editing session terminates abnormally, for example, you must delete or rename any backup le before you can resume editing your 4GL module or form from the Programmers Environment. This concludes the description of the Rapid Development System. Except as otherwise noted, the descriptions of INFORMIX-4GL elsewhere in this manual describe features that are identical in both the C Compiler Version and Rapid Development System implementations of INFORMIX-4GL.

Compiling 4GL Source Files

1-73

RDS Program Filename Extensions

1-74

Compiling 4GL Source Files

Chapter

INFORMIX-4GL Programming
Chapter Overview 3 Language Conventions 3 Comments 3 INFORMIX-4GL Identiers 4 Scope of Identiers 4 Constants 5 String Constants 5 Integer Constants 5 Floating Number Constants 5 Date and Time Constants 6 Program Variables 6 Data Types 7 SMALLINT 7 INTEGER 7 DECIMAL [ (m [, n ] ) ] 7 SMALLFLOAT 8 FLOAT [ ( n ) ] 8 MONEY [ ( m [ , n ] ) ] 8 CHAR [ ( n ) ] 8 DATE 9 DATETIME 9 INTERVAL 9 LIKE table.column 9 RECORD 9 ARRAY [i, j, k] OF type 10 Data Conversion 10

Operators and Expressions 11 Number Expressions 11 String Expressions 12 Date and Time Expressions 12 Boolean Expressions 13 Expressions in INFORMIX-4GL Statements Binding to Database and Forms 14 The THRU Keyword and the .* Notation 15 INFORMIX-4GL Statements 16 Variable Denition 17 Assignment 17 Program Organization 17 Program Flow 18 Screen Interaction 19 Report Generation 21 Error and Exception Handling Error Handling 22 Exception Handling 23 Data Validation 23

13

21

Built-in Functions 24 ASCII 25 CLIPPED 27 COLUMN 29 CURRENT 30 DATE 32 DATE( ) 33 DAY( ) 34 EXTEND( ) 35 LENGTH( ) 38 MDY( ) 39 MONTH( ) 40 TIME 41 TODAY 42 UNITS 43 USING 44 Formatting Number Expressions 44 Formatting DATE Expressions 46 WEEKDAY( ) 53 YEAR( ) 54 C Functions 55

2-2

INFORMIX-4GL Programming

Chapter Overview
An INFORMIX-4GL program consists of one or more source les, each containing a series of English-like statements that obey a well-dened syntax. This chapter describes the syntax rules and gives an overview of those statements that do not apply directly to a database. It lists the built-in 4GL functions and describes how to write C functions that can be called by INFORMIX-4GL programs, if you have a C compiler.

Language Conventions
The INFORMIX-4GL programming language contains identiers, keywords, constants, operators, and expressions. It makes no distinction between uppercase and lowercase letters. It is completely free-form, like C or Pascal, and ignores any extra spaces, tabs, linefeeds, and comments. When necessary, it uses the keyword END in association with the statement type to terminate a statement. Apart from this, it has no statement terminators such as the semicolon.

Comments
For clarity and to simplify program maintenance, it is recommended that you document your code by including comments in your 4GL source les. You can also use comment symbols during program development to disable statements without deleting them. You can indicate comments in any of three ways:

A comment can begin with the left brace ( { ) and end with the right brace
( } ). You cannot use braces to nest comments.

You can also use the pound sign ( # ) to begin a comment. The comment
terminates at the end of the line.

INFORMIX-4GL Programming

2-3

INFORMIX-4GL Identiers

You can also use a pair of hyphens or minus signs (--) to begin a comment that terminates at the end of the line. (Use of this comment indicator conforms to the ANSI standard.) All text between the braces (or from the # or -- indicator to the end of the line) is ignored.

INFORMIX-4GL Identiers
INFORMIX-4GL programs can reference constants, local, module, and global

program variables, screen forms, labels, windows, functions, and reports. With the exception of constants, each of these must have an INFORMIX-4GL identier as a name. An identier is a sequence of letters, digits, and underscores ( _ ). The rst character must be a letter or an underscore. Only the rst eight characters are signicant, and the case of letters is ignored. Identiers must not be the same as keywords (which are listed in Appendix D).
INFORMIX-4GL identiers can be the same as SQL identiers, but such use requires special attention when you use the identier in an SQL statement. (See Chapter 3 for a discussion of SQL statements, objects, cursors, and identiers.)

Scope of Identiers
Program variables can be either local, modular, or global in their scope of reference.

Local variables must be dened within a MAIN, FUNCTION, or REPORT

program block. They cannot be referenced by statements outside that program block.

Module variables must be dened before the rst program block (that is,
before the MAIN statement or before any REPORT or FUNCTION statement). They can be referenced only by statements in the same module.

Global variables must be dened either prior to the MAIN statement

(and in a DEFINE statement preceded by a GLOBALS statement and followed by an END GLOBALS statement) or in a separate globals le. Other program les using these variables must include the statement GLOBALS globals-lename (where globals-lename contains the denitions of the global variables).

2-4

INFORMIX-4GL Programming

Constants

Forms, cursors, functions, reports, windows, and some 4GL statements have identiers that are not program variables. The scope of reference for identiers of forms, windows, functions, and reports is the entire program. The scope of the identiers of cursors and PREPAREd statements is from where you DECLARE or PREPARE them until the end of the same module.

Constants
4GL supports string, integer, oating number, and date and time constants. INFORMIX-4GL recognizes three predened constants: TRUE = 1, FALSE = 0, and NOTFOUND = 100. It also permits the assignment of the value NULL to variables and to database columns. NULL values are distinct from blank

strings or zeros for number variables and columns, and represent unknown values. See the section NULL Values in Chapter 3 for details about the behavior of NULL values in expressions.

String Constants
String constants are sequences of up to 80 characters enclosed within double quotes. The constant must be written on a single line (no embedded new lines). You can create longer string variables by concatenating string constants. To include a double quote in a string, precede the double quote with the backslash or repeat the double quote, as in these two equivalent strings:
"Enter \"y\" to select this row" "Enter ""y"" to select this row"

The single quote has no special signicance in string constants.

Integer Constants
You must express integer constants in decimal notation without embedded commas and without a decimal point. You can precede the integer with a minus or plus sign, but there can be no space, tab, or new line between the sign and the rst digit:
15 -12 13938

Floating Number Constants

Non-integer number constants are expressed only in base 10 with a decimal point. You can use exponential notation as well:
123.456 = 1.23456e2 = 123456.0e-3

INFORMIX-4GL Programming

2-5

Program Variables

Date and Time Constants

String constants that evaluate to DATE values must be enclosed within double quotation marks and can be expressed either with the format mm/dd/yy or with mm/dd/yyyy. The mm stands for the month (1 or 01 for January, 2 or 02, for February, and so on). The dd stands for the day of the month (from 1 to the maximum for that month). Both yy and yyyy stand for the year. When you use only two digits for the year, INFORMIX-4GL assumes that you intend to enter a year beginning with the digits 19. Values of data types DATETIME or INTERVAL can appear as constants within double quotation ( " ) marks, as in:
"1989-11-23 19:30:00"

or as unquoted literals of the form:

type (values) qualier

where type is the keyword DATETIME or INTERVAL, values are a list of calendar date values and/or time-of-day values for DATETIME, or else date or time values for INTERVAL; and qualier identies the largest and smallest units that the values describe. The following example species an instant in time on March 6th, 1989, and illustrates the delimiters that separate elds within the values:
DATETIME (89-3-6 09:55:30.825) YEAR TO FRACTION(3)

You can prex an INTERVAL literal with + or - to indicate a positive or negative interval. If the qualier is only a single eld, an INTERVAL can also be of the form:
expression UNITS eld

Here expression is a number expression, and eld is one of the keywords YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, or FRACTION (n). (The last designates n decimal-place fractions of a second, for 1 n 5.) For example, this means six months:
6 UNITS MONTH

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

Program Variables
Information transfer among a 4GL screen, report, and database occurs through named memory locations called program variables. You must dene the data storage required by a program variable before you can
2-6 INFORMIX-4GL Programming

Data Types

use that variable in an INFORMIX-4GL program. You do this by assigning an identier to the variable and associating it with a data type, using the DEFINE statement. (See Chapter 7 for details.)

Data Types
INFORMIX-4GL variables must have one of the following data types: SMALLINT INTEGER INT DECIMAL [ (m [ , n ] ) ] DEC [ ( m [ , n ] ) ] NUMERIC [ (m [ , n ] ) ] SMALLFLOAT REAL RECORD [ LIKE table. * ] FLOAT [ ( n ) ] DOUBLE PRECISION [ ( n ) ] MONEY [ (m [ , n ] ) ] CHAR [ ( n ) ] CHARACTER [ (n ) ] DATE DATETIME qualier INTERVAL qualier

ARRAY [ i , j , k ] OF type

SMALLINT
This data type includes whole numbers in the range -32,767 to +32,767.

INTEGER
This data type includes whole numbers in the range -2,147,483,647 to +2,147,483,647. You can use the INT keyword as a synonym for INTEGER.

DECIMAL [ (m [, n ] ) ]
This data type includes decimal oating-point numbers with a total of m ( 32) signicant digits (the precision) and n ( m) digits to the right of the decimal point (the scale). When you give values for both m and n, the decimal variable obeys xed-point arithmetic. All numbers with an absolute value less than 0.5 10-n have the value zero. The largest absolute value of a variable of type DECIMAL that can be stored without an error is 10m-n -10-n. The second parameter is optional. If it is missing, INFORMIX-4GL treats the variable as a oating decimal. DECIMAL(m) variables have a precision of m, and a range in absolute value from 10-128 to 10126 When printed without formatting instructions, DECIMAL(m) variables have two decimal places to the
INFORMIX-4GL Programming 2-7

Data Types

right of the decimal point (and an exponent, if necessary). If you designate no range or precision parameters, the default is DECIMAL(16), a oating decimal. You can also use the keywords DEC or NUMERIC as synonyms for DECIMAL.

SMALLFLOAT
This data type includes binary oating-point numbers corresponding to the oat data type of the C language. You can use the keyword REAL as a synonym for SMALLFLOAT.

FLOAT [ ( n ) ]
This data type includes oating-point numbers corresponding to the double C data type. Here (n), a whole number between 1 and 14, is an optional parameter to specify the precision. INFORMIX-4GL does not use this parameter, which is provided for compatibility with the ANSI standard. You can use the keywords DOUBLE PRECISION as a synonym for FLOAT.

MONEY [ ( m [ , n ] ) ]
Like the DECIMAL data type, the MONEY data type can also take two parameters. The range of values for columns of type MONEY(m, n) is the same as for columns of type DECIMAL(m, n), but variables of type MONEY are displayed with a currency symbol (by default, the dollar sign). The type MONEY(m) is dened as DECIMAL(m, 2) and, if no parameter is given, MONEY is taken to be DECIMAL(16, 2). Regardless of the number of parameters, INFORMIX-4GL always treats the data type MONEY as a xed decimal number.

CHAR [ ( n ) ]
These are character strings of length n (where 1 n 32,767). If you use the keyword CHAR and do not specify a length, INFORMIX-4GL interprets this to mean CHAR(1). You can refer to substrings of CHAR type program variables in LET, ERROR, MESSAGE, and PROMPT statements with the notation charvariable[m,n], which selects the mth through the nth components of the variable char-variable. (The square brackets are literal, not symbols to indicate an option.) You can use the keyword CHARACTER as a synonym for CHAR.

2-8

INFORMIX-4GL Programming

Data Types

DATE
These are dates from a DATE column or expression, or entered as a character string in one of the formats described earlier in the DATE subsection of Date and Time Constants. INFORMIX-4GL stores a DATE variable as an integer, whose value is the number of days since December 31, 1899.

DATETIME
These are instants in time, including both the date and the time-of-day specications. A DATETIME value species a contiguous sequence of the elds: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and FRACTION (of a second). A value is entered as a character string, in one of the formats described earlier in the section Date and Time Constants. Values are stored internally as decimal numbers with a scale of zero, with a precision factor corresponding to the number of digits implied by the elds. See Appendix J, Working with DATETIME and INTERVAL Data.

INTERVAL
This data type includes signed intervals of time, measured in one or more of the same units as DATETIME. A value is entered as a character string in one of the formats described earlier in the section Date and Time Constants. INTERVAL values specify a contiguous sequence from one of these lists of elds: YEAR and MONTH, or DAY, HOUR, MINUTE, SECOND, and FRACTION (of a second), but you can specify a non-default precision for a eld. Internal storage is the same as for DATETIME values. See also Appendix J, Working with DATETIME and INTERVAL Data.

LIKE table.column
You can dene the data type of a variable indirectly by indicating that it should have the same data type as a column in the database. If the column has type SERIAL, INFORMIX-4GL assigns it the data type INTEGER but enforces none of the other restrictions on SERIAL types. (Chapter 3 contains the denition of the SERIAL data type.)

RECORD
This data type describes a set of variables of possibly differing data types, including other records. You can refer to individual elements as record_name.element_name and often to record-name.* for the entire set. (But see The THRU Keyword and the .* Notation, later in this chapter for limitations on using record-name.*.) You can dene a record by listing its elements
INFORMIX-4GL Programming 2-9

Data Conversion

and their types, or by dening it to be LIKE table.* , where table is a table in the database. If dened LIKE table.*, the elements of the record have the same names as the columns of table, and the same corresponding data types.

ARRAY [i, j, k] OF type

This data type describes i j k variables of the same data type. ARRAY variables can have from one to three dimensions. You can have arrays of records, but not arrays of arrays. Here the square brackets ( [ ] ) are required and do not represent an option. If char-array[i,j,k] is an array of CHAR type, you can select a substring of one of its components with the chararray[i,j,k][m,n] notation. In this example, i,j,k are indexes into the array, m is the starting position of the substring, and n is the stopping position of the substring. Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

Data Conversion
INFORMIX-4GL performs data-type conversion without objection when the process makes sense. If you assign a number expression to a CHAR variable, INFORMIX-4GL converts the resulting number to a string. If you use a string representation of a number or a date in an arithmetic expression, INFORMIX-4GL converts the string or date to an appropriate number. INFORMIX-4GL produces an error message only if it could not make the conversion.

For example, it converts the string 123.456 to the number 123.456 in an addition, but adding the string John to a number produces an error.
INFORMIX-4GL carries out all arithmetic in an arithmetic expression in type DECIMAL. The type of the resulting variable determines the format of the

stored or printed result. The following rules apply to the precision and scale of the DECIMAL variable that results from an arithmetic operation on two numbers:

All operands, if not already DECIMAL, are converted to DECIMAL, and the
resulting number is DECIMAL.
Convert Type FLOAT SMALLFLOAT INTEGER SMALLINT To DECIMAL(16) DECIMAL(8) DECIMAL(10,0) DECIMAL(5,0)

The precision and scale of the result of an arithmetic operation depend on

the precision and scale of the operands and on the type of arithmetic
2-10 INFORMIX-4GL Programming

Operators and Expressions

expression. The rules are summarized in the table at the end of this section for arithmetic operations on operands with denite scale. When one of the operands has no scale (oating decimal), the result is a oating decimal.

In addition and subtraction, INFORMIX-4GL adds trailing zeros to the

operand with the smallest scale until the scales are equal.

If the type of the result of an arithmetic operation requires the loss of signicant digits INFORMIX-4GL reports an error.

Leading or trailing zeros are not considered signicant digits, and do not
contribute to the determination of precision and scale. In this table, p1 and s1 are the precision and scale of the rst operand, and p2 and s2 are the precision and scale of the second operand.
Operation Addition and Subtraction Multiplication Division Precision and Scale of Result Precision: MIN(32, MAX(p1 - s1, p2 - s2) + MAX(s1, s2) + 1) Scale: MAX(s1, s2) Precision: Scale: Precision: Scale: MIN(32, p1+ p2) s1 +s2 32 32 - p1 + s1 - s2 (This cannot be negative.)

Operators and Expressions

INFORMIX-4GL expressions can be categorized as number, string, date and time, and Boolean. Number expressions can be either integer (evaluating to INTEGER or SMALLINT) or non-integer (evaluating to FLOAT, SMALLFLOAT, MONEY, or DECIMAL). Because of the automatic conversion capability of INFORMIX-4GL, DATE type variables can occur in integer, string, or date and time expressions. Number variables can occur in number, string, or date and time expressions.

Number Expressions
A number expression consists of a number constant, variable, column name, or function that returns a number value; or one of these, connected to a number expression by one of these arithmetic operators:

INFORMIX-4GL Programming

2-11

Operators and Expressions

Operator ** * / mod + -

Operation Exponentiation Multiplication Division Modulus Addition Subtraction

String variables that are character representations of numbers are converted to numbers when used in number expressions. A string that is not a character representation of a number causes an error if used in a number expression.

String Expressions
A string expression is a string constant, a CHAR type variable or column, or a function returning a CHAR type; or any combination of these, combined or altered by the following string operators:
Operator , [m,n] CLIPPED USING WORDWRAP Operation Concatenation Substring where m is the starting position and n is the ending position Drop trailing blanks Formatting Display long strings in multiple lines

Number constants, variables, and columns are converted to their character representation when used in string expressions. See the description of the USING function near the end of this chapter for information about formatting numbers and dates. The WORDWRAP function is used only in 4GL reports, and is described in Chapter 5. The next page lists 4GL Boolean operators on string expressions.

Date and Time Expressions

Date and time expressions are constants, variables, column names, string literals, or expressions with the UNITS, TODAY, or CURRENT keywords that evaluate to a DATE, DATETIME, or INTERVAL value. They can also be any date or time expression combined with another date or time expression (or with a number) by an arithmetic operator, as summarized in the Operations on DATETIME and INTERVAL Values section of Appendix J. Some arithmetic operations involving date and time values require that you use the EXTEND function to adjust the precision of the date or time value. You can read more about EXTEND later in this chapter.
2-12 INFORMIX-4GL Programming

Operators and Expressions

Boolean Expressions
A Boolean expression evaluates to TRUE or FALSE (or UNKNOWN, if NULL values are involved) and can take any of the following forms:

expr rel-op expr

Here expr is an expression and rel-op is a relational operator:
Operator = != or <> > >= < <= Operation Equal to Not equal to Greater than Greater than or equal to Less than Less than or equal to

(For string expressions, greater than means after in the ASCII collating order, as listed in Appendix H. Lowercase letters are after uppercase letters, which are after numerals. For DATE and DATETIME values, greater than means later in time.)

string-expr [ NOT ] LIKE string-expr [ ESCAPE " esc-char " ] string-expr [ NOT ] MATCHES string-expr expr IS [ NOT ] NULL expr [ NOT ] BETWEEN expr AND expr expr [ NOT ] IN ( { items | SELECT-statement } ) expr rel-op { ALL | ANY | SOME } ( SELECT-statement )
EXISTS ( SELECT-statement )

[ ESCAPE " esc-char " ]

The last four expressions apply only in WHERE clauses of SELECT statements. (See The SELECT Statement near the end of Chapter 7 for details and for an explanation of the ESCAPE keyword.) Boolean expressions can be compounded with the operators NOT, AND, and OR:
[ NOT ] Boolean-expr [ { AND | OR } Boolean-expr ]

Expressions in INFORMIX-4GL Statements

For the CASE, IF, and WHILE statements in INFORMIX-4GL, TRUE is any non-zero number and FALSE is zero. In these statements you can use a number expression where a Boolean expression is called for. You can use a Boolean expression where a number expression would be expected, yielding 1 or 0. You can use a string expression that is a representation of a number

INFORMIX-4GL Programming

2-13

Binding to Database and Forms

anywhere that a number expression is allowed. If you use a string expression where a Boolean expression is expected and the string expression does not represent a number, it will be evaluated as zero or FALSE. A Boolean expression containing a NULL value has an UNKNOWN truth value, but it is treated as FALSE in INFORMIX-4GL statements. This can lead to unfamiliar consequences. If a is a Boolean expression, the compound expression a OR NOT a would be tautologically TRUE in two-valued logic. If a contains a NULL value (and does not contain the IS NULL keywords), its truth value is UNKNOWN. The truth value of NOT a is also UNKNOWN. INFORMIX-4GL treats both these and their combination with OR as FALSE. If there is any chance that a variable may have a NULL value, you should test it before using it in a Boolean expression. See the section NULL Values in Chapter 3 for more details.

Binding to Database and Forms

Regardless of how you have dened them, there is no implicit relationship between program variables, screen elds, and database columns. Even when a variable lname is dened to be LIKE customer.lname, changes to the program variable do not imply any change in the column value. Similarly, even if you created screen eld customer.lname using the same database column as a model, there is no inherent connection between the program variable and the eld. You must indicate the binding explicitly in any 4GL statement that connects program variables to screen forms or to database columns. The following two statements take input from the screen and insert the value entered on the screen into the database. Here the @ sign tells INFORMIX-4GL that the rst lname is the name of a database column.
INPUT lname FROM customer.lname INSERT INTO customer (@lname) VALUES (lname)

Some statements permit temporary binding through the identity of the variable name and the screen eld name. (See the individual statement descriptions in Chapter 7 for the appropriate syntax.) The following statement could replace the previous INPUT statement:
INPUT BY NAME lname

2-14

INFORMIX-4GL Programming

The THRU Keyword and the .* Notation

The THRU Keyword and the .* Notation

INFORMIX-4GL provides two devices to simplify the writing of 4GL statements that refer to elements of a record or columns of a table. One of these devices involves the keyword THRU (or THROUGH, its synonym), and the other involves the .* notation. INITIALIZE pr_rec.element4 THRU pr_rec.element8 TO NULL DISPLAY pr_rec.* TO sc_rec.*

The INITIALIZE statement above sets to NULL the values of program variables pr_rec.element4, pr_rec.element5, pr_rec.element6, pr_rec.element7, and pr_rec.element8. The DISPLAY statement lists the entire record pr_rec on the screen elds described by the screen record sc_rec. (Chapter 4 describes screen records.) With one exception, discussed at the end of this section, these devices are a shorthand for writing out a partial or full list of record elements or the columns of a table, with comma ( , ) separating individual items. The order of the items in the list is the order they had when dened. There are, however, the following limitations on their use:

You cannot use THRU in reference to columns of database tables. There is

no shorthand for a partial listing of columns of a table.

In the denition of a screen record, THRU runs through all the elds in the
order that they are listed in the ATTRIBUTES section of the form specication le, from the eld rst named to the last. An example follows:
ATTRIBUTES ... f002=tab1.aa; f003=tab1.bb; f004=tab1.cc; f005=tab2.aa; f006=tab2.bb; f007=tab3.aa; f008=tab3.bb; f009=tab3.cc; ... INSTRUCTIONS SCREEN RECORD sc_rec (tab1.cc THRU tab3.bb)

INFORMIX-4GL Programming

2-15

INFORMIX-4GL Statements

The previous excerpt from a form specication le leads to the following list of elements of sc_rec:
tab1.cc tab2.aa tab2.bb tab3.aa tab3.bb

You cannot use THRU to indicate a partial list of screen record elements
when displaying to a form or inputting from a form.

You cannot use either THRU or the .* notation on a record that contains an
array among its elements. For example, you cannot use myrec.* to refer to all the elements of a record dened as follows:
DEFINE myrec RECORD ri INTEGER, ra ARRAY[2] OF INTEGER END RECORD

You can use the .* or THRU notation, however, for records that contain
records as elements.

You cannot use THRU or the .* notation in the argument list when dening
a function or report program block. You can, however, list a record as an argument of a function or of a report. The exception to .* expanding to a list occurs when you use it in a 4GL UPDATE statement. The notation
UPDATE table1 SET table1.* = pr_rec.*

is expanded by INFORMIX-4GL to the proper syntax

UPDATE table1 SET table1.col1 = pr_rec.element1, table1.col2 = pr_rec.element2, ...

but with all SERIAL columns omitted. (The SERIAL data type is described in Chapter 3.)

INFORMIX-4GL Statements
Eight statement types in INFORMIX-4GL do not deal with the database. These statement types are listed in the sections that follow:

2-16

INFORMIX-4GL Programming

Variable Denition

Variable Denition
You must dene all program variables before you can use them.
DEFINE

associates an INFORMIX-4GL identier with a data type. DEFINE statements must be the rst statements within a program block (to dene local variables) or must be within a GLOBALS statement (to dene global variables). Variables dened after the GLOBALS section (if it is present) and before MAIN, the rst FUNCTION, or rst REPORT section of a program module have modular scope.

Assignment
You can assign values directly to program variables with one of two statements:
LET

assigns the value of an expression to a simple program variable or to a component of an array or a record. You cannot use a single LET statement to assign values to an entire record or an array. assigns default or NULL values to a program variable. Through the upscol utility, described in Appendix E, you can set default values for any columns in your database that are not DATETIME or INTERVAL. You can then use the INITIALIZE statement to assign these default values to simple or record variables.

INITIALIZE

Program Organization
INFORMIX-4GL programs can have three different types of program blocks: MAIN, FUNCTION, and REPORT. Programs can also contain global declara-

tion statements.
MAIN

contains one or more INFORMIX-4GL statements and must occur once, and only once, in every INFORMIX-4GL program. INFORMIX-4GL passes program control initially to the MAIN program block when you execute your program. The last statement in the MAIN program block must be the END MAIN statement. After INFORMIX-4GL executes the END MAIN statement, it terminates the program. contains a sequence of INFORMIX-4GL statements that perform a desired task and terminates with the END FUNCTION statement. A function can return zero or more values to the
INFORMIX-4GL Programming 2-17

FUNCTION

Program Flow

routine that called it. You can pass the values of variables to functions as parameters.
REPORT GLOBALS

contains format and output specications for a report. identies those program variables that have a global scope of reference.

A program must contain only one MAIN statement, and can have at most one GLOBALS statement that includes DEFINE statements. No restrictions apply to the number of FUNCTION or REPORT program blocks that can appear in a program or in a module. (A module is a system le that contains one or more program segments.) You can place all program blocks in a single module, or put each function in a separate module, or use any combination in between. A GLOBALS statement containing DEFINE statements must either be in a module by itself or be the rst statement (or the second if a DATABASE statement also appears in the module) in the module containing the MAIN program block. Any module containing routines that refer to global variables must begin with a GLOBALS statement giving the pathname of the module that denes the global variables. (See the GLOBALS statement in Chapter 7 for full details.) Modules can be compiled separately and linked later, permitting you to create a library of INFORMIX-4GL functions and to call them from different modules. In addition, your program can call C functions. See the section C Functions, later in this chapter, for the rules governing C functions called by INFORMIX-4GL programs.

Program Flow
INFORMIX-4GL has many statements that control the ow of a program. These statements are included in INFORMIX-4GL because they simplify

the programming process.

CALL

is used to call a function that returns zero or more values. You can only use a function that returns a single value within an expression. begins an indexed loop of statements (ended by END FOR) that will be executed until the index reaches a programmersupplied value. begins a loop of statements (ended by END FOREACH) that will be executed for each row that is returned by a query of the database.

FOR

FOREACH

2-18

INFORMIX-4GL Programming

Screen Interaction

WHILE

begins a loop of statements (ended by END WHILE) that will be executed until a programmer-supplied Boolean expression becomes false. permits a premature cycling of a loop or menu. permits a premature exit from a FOR, FOREACH, WHILE, MENU, INPUT, or CASE statement, or from the entire program. executes one or more statements conditionally (ended by END IF). executes a different sequence of statements (ended by END CASE) depending upon the current value of an expression. passes program control immediately to a designated place in the program. marks the place in the program where a GOTO statement can pass control. causes the program to pause for a specied length of time. executes an operating system program and returns control to the INFORMIX-4GL program.

CONTINUE EXIT

IF CASE GOTO LABEL SLEEP RUN

Screen Interaction
The next 18 statements allow the program to interact with the screen. The rst statement constructs a menu; the next ve statements provide control over clearing the screen, printing messages, retrieving user input, and setting up default values for screen parameters, special keys, and help les. The next three statements are window management statements. The last nine statements handle the entry and retrieval of data from screen forms.
MENU

creates a ring menu with help lines, associated help screens, and a description of program behavior for each menu option. optionally clears specic screen elds, all screen elds, the entire screen, or a window. prints a message in reverse video on the Error line and rings the terminal bell. prints a message on the Message line. prints a message on the Prompt line and returns the users response.

CLEAR ERROR MESSAGE PROMPT

INFORMIX-4GL Programming

2-19

Screen Interaction

OPTIONS

OPEN WINDOW

CURRENT WINDOW CLOSE WINDOW OPEN FORM DISPLAY FORM CLOSE FORM CONSTRUCT

species the Message, Prompt, Form, and Comment lines relative to the screen or current window, as well as any key and help le designations. You can also specify a new Error line with the OPTIONS statement, but the error line remains relative to the screen. creates a window, with or without a border, at a given location and makes it available for use. You can explicitly specify the size of the window or let INFORMIX-4GL determine the size of the window from a given screen form. species the current or topmost window. All input and output is done in the current window. closes the window that you specify, restoring the topmost window (of those that remain) as the current window. opens the compiled screen form and associates an INFORMIX-4GL identier with the form. displays the named form on the screen or in a window, displacing whatever was on the screen or window below the Form line. closes the le containing the named screen form and releases its association with the INFORMIX-4GL identier. takes user input from a screen form and creates a character string that can be used as the WHERE clause of a SELECT statement. This is the INFORMIX-4GL mechanism for performing a query-by-example. displays expressions and variables in elds of a screen form, at a specic position on the screen, in a window, or on the next line. displays a program array to a screen array and allows scrolling through the array. takes user-entered data from a screen form and puts the data into program variables. You can specify sequences of statements to be executed during the INPUT statement before or after the cursor enters any eld or after the user indicates that entry is complete. You can also trap function or control keys and specify an appropriate sequence of statements. is an extension of the INPUT statement that takes data entered by a user into a screen array and puts the information into an array of program variables. The user can scroll through the array, insert new rows into the array, and delete rows from the array by using function keys.

DISPLAY

DISPLAY ARRAY INPUT

INPUT ARRAY

2-20

INFORMIX-4GL Programming

Report Generation

SCROLL

moves data in a screen array up or down.

Report Generation
There are three statements in INFORMIX-4GL that control report writing. signals INFORMIX-4GL to initialize the report. Optionally, START you can specify the output device in the START REPORT REPORT statement. passes a row of the report variables to the report. This stateOUTPUT TO ment is usually found within a FOREACH loop where the REPORT report row is the current row of a query. handles the end of report summaries and, if necessary, secFINISH ond passes through the data so that aggregate values can be REPORT calculated.

Error and Exception Handling

INFORMIX-4GL allows you to trap run-time errors and warnings, and userentered Interrupt (usually DEL or CTRL-C) and Quit (CTRL-\) signals. For non-MODE ANSI databases, the default effects are that errors, Interrupts, and Quits cause immediate program termination, while warnings are ignored. (In a MODE ANSI database, processing continues by default after an error though not after an Interrupt or Quit.) You can change these defaults with the following commands: WHENEVER

allows you to trap errors, warnings, and NOTFOUND conditions, and to instruct INFORMIX-4GL to call a function, go to a statement, terminate the program, or ignore the problem. In the last case (WHENEVER ERROR CONTINUE), you must test for errors explicitly after every statement where an error would produce difculties in your program. allows you to prevent INFORMIX-4GL from terminating a program when the user presses the Interrupt or Quit keys. If you choose this option, the Interrupt and/or Quit keys will terminate INPUT, INPUT ARRAY, CONSTRUCT, and PROMPT statement but will not terminate the program. You must explicitly check the global variables int_ag and quit_ag to determine whether the user has pressed the Interrupt or Quit keys after these statements.

DEFER

INFORMIX-4GL Programming

2-21

Error and Exception Handling

Error Handling
INFORMIX-4GL sets the global variable status following the execution of every SQL or form-related INFORMIX-4GL statement. status is zero when the statement executes correctly, negative when there is an error, and equal to NOTFOUND (= 100) when you attempt a FETCH outside the range of the active list of rows, or when a SELECT statement can nd no rows. (See Chapter 3 for more information on the FETCH and SELECT statements.)

Three library functions, described later in this section, are available to the INFORMIX-4GL programmer to identify errors from the status variable. (Chapter 6 describes all the 4GL library functions.) The WHENEVER statement is designed to trap errors, warnings, and the NOT FOUND condition in the execution of other statements. INFORMIX-4GL indicates errors, warnings, and NOT FOUND conditions by supplying values for the global record SQLCA. See Chapter 3 for a description of the SQLCA record, and Chapter 7 for syntax of WHENEVER. The WHENEVER statement has the effect of writing an IF statement after each subsequent SQL statement in the source-code module to test for an exceptional condition, and species an action to take if the condition is detected. Without a WHENEVER statement, the default action after a warning or NOT FOUND is CONTINUE. For errors, however, the default depends on your type of database. Your 4GL compiler identies the database that your program declares in the DATABASE statement that precedes the rst program block (the MAIN program block, or the rst function or report program block). If this database is MODE ANSI at compile-time, the default action after an error is CONTINUE. Otherwise, the default action for ERROR is STOP. The scope of a WHENEVER ERROR statement is the module in which it occurs, and from the position of the WHENEVER ERROR statement to the next WHENEVER ERROR statement in the module (or to the end of the module, if no more WHENEVER ERROR statements appear in the module). The scope of reference of WHENEVER WARNING and WHENEVER NOT FOUND statements are similar, extending to the end of the module, or else to the next WHENEVER statement that species the same condition in the same source code module. If you do not specify WHENEVER ERROR CONTINUE, then the startlog( ) function causes the routine name, the error code, and the corresponding error message to be written to a designated error le every time an error occurs. The syntax for startlog( ) is
CALL startlog ( lename ) 2-22 INFORMIX-4GL Programming

Data Validation

where lename is a quoted string that species the name of the error log le, or a CHAR variable that evaluates to the name of the error log le. If you do not want the error log le to reside in the current directory, you must specify a pathname. Another library function, errorlog("message"), appends the quoted string or CHAR variable message to the error log. This function allows you to write directly to the error log le. Chapter 6 describes these and three other 4GL library functions that deal with errors: err_print( ) err_get( ) err_quit( ) If passed the error code, prints the message on the Error line. If passed the error code, returns the message to a string variable. If passed the error code, prints the message on the Error line, and exits from the program.

Exception Handling
You can also trap Interrupt (usually DEL or CTRL-C) and Quit signals (CTRL-\) that users send to your INFORMIX-4GL program. The syntax is
DEFER { INTERRUPT | QUIT }

The DEFER keyword means that a global ag (int_ag for INTERRUPT and quit_ag for QUIT) is set to non-zero and can be checked by the program. It is the programmers responsibility to reset the ags to zero. The default for either an Interrupt or a Quit signal is to cause the INFORMIX-4GL program to stop immediately. If the user enters an Interrupt during an INPUT or INPUT ARRAY statement and you have executed the DEFER INTERRUPT statement, the program control leaves the INPUT statement and INFORMIX-4GL sets int_ag. You can enter the DEFER INTERRUPT statement only once in a program, and then only in the MAIN program block. This restriction applies to the DEFER QUIT statement as well.

Data Validation
You can ensure that data entered through a form conform to appropriate limits or have permitted values by setting up the INCLUDE attribute in the form specication or in the syscolval table. (See in Chapter 4 for a discussion

INFORMIX-4GL Programming

2-23

Built-in Functions

of these concepts.) If your program inserts data into the database from sources other than a form, you can check that the data meets these same restrictions by using the VALIDATE statement. VALIDATE issues an error if the value of a program variable is not consistent with limitations set for the corresponding column in syscolval.

If the current database is not MODE ANSI, then the upscol utility creates a single syscolval table that can specify acceptable values or ranges of values for any or all database columns. The VALIDATE statement enforces the limitations specied in this table. In a MODE ANSI database, however, each user of upscol creates an individual owner. syscolval table. When INFORMIX-4GL subsequently processes a VALIDATE statement of the form:
VALIDATE variable-list LIKE [ owner. ] table. column

it compares variable-list to the syscolval table belonging to the owner of the table. (The owner prex can be omitted if the user who compiled the current 4GL program is the owner.) If owner. syscolval does not exist, the VALIDATE statement takes no action.

Built-in Functions
In addition to functions that you create with a FUNCTION statement and C functions that you can call, INFORMIX-4GL provides a number of pre-dened functions, operators, and keyword expressions. You can use the following functions, operators, and keywords in expressions.
ASCII CLIPPED COLUMN CURRENT DATE DATE( ) DAY( ) EXTEND( ) LENGTH( ) MDY( ) MONTH( ) TIME TODAY UNITS USING WEEKDAY( ) YEAR( )

These are described in the sections that follow. There are additional functions that can be used only within REPORT program blocks (described in Chapter 4) and INFORMIX-4GL library functions that cannot be used in SQL statements (described in Chapter 6). Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.
2-24 INFORMIX-4GL Programming

ASCII

ASCII
Overview
This function evaluates an integer argument as the corresponding ASCII character.

Syntax
ASCII num-expr

Explanation
ASCII

is a required keyword.

num-expr is a number expression.

Notes
INFORMIX-4GL evaluates this function as a single character. You can use it to display CTRL characters.

Examples
The following DISPLAY statement rings the terminal bell (ASCII value of 7).
DEFINE bell CHAR(1) LET bell = ASCII 7 DISPLAY bell

The next REPORT program block fragments show how to implement special printer or terminal functions. They assume that, when the printer receives the sequence of ASCII characters 9, 11, and 1, it will start printing in red, and

INFORMIX-4GL Programming

2-25

Examples

when it receives 9, 11, and 0, it will revert to black printing. The values used in the example are hypothetical; refer to your printer or terminal manual for information on your printer or terminal.
FORMAT FIRST PAGE HEADER LET red_on = ASCII 9, ASCII 11, ASCII 1 LET red_off = ASCII 9, ASCII 11, ASCII 0 ON EVERY ROW ... PRINT red_on, "Your bill is overdue.", red_off ...

Caution: INFORMIX-4GL cannot distinguish printable and non-printable ASCII characters. Be sure to account for the non-printing characters when using the COLUMN function to format your page. Since various devices differ in outputting spaces with CTRL characters, you may have to use trial and error to line up columns when you output CTRL characters.

2-26

INFORMIX-4GL Programming

CLIPPED

CLIPPED
Overview
CLIPPED displays the character expression that precedes it without any trailing blanks.

Syntax
char-expr CLIPPED

Explanation
char-expr is a required character expression.
CLIPPED

is a required keyword.

Notes
1. You normally use CLIPPED after a variable name in a LET or DISPLAY statement, or in a PRINT section of a REPORT program block. 2. CLIPPED affects the value of a character variable when it is used as an expression. CLIPPED does not affect the value when it is stored in a variable (unless you are concatenating CLIPPED values together). For example, if CHAR variable b contains a string that is shorter than the data type of a, the following LET statement pads a with trailing blanks, despite the CLIPPED keyword:
LET a = b CLIPPED

The following statement displays b without trailing blanks:

DISPLAY b CLIPPED AT 1,12

INFORMIX-4GL Programming

2-27

Example

Example
The following example is from a REPORT program block that prints mailing labels.
FORMAT ON EVERY ROW IF (city IS NOT NULL) AND (state IS NOT NULL) THEN PRINT fname CLIPPED, 1 SPACE, lname PRINT company PRINT address1 IF (address2 IS NOT NULL) THEN PRINT address2 END IF PRINT city CLIPPED, ", " , state, 2 SPACES, zipcode SKIP TO TOP OF PAGE END IF

2-28

INFORMIX-4GL Programming

COLUMN

COLUMN
Overview
The COLUMN function returns a string of spaces long enough to begin the next item in the designated column.

Syntax
COLUMN integer-expr

Explanation
COLUMN

is a required keyword. is a required positive integer expression that species the initial column number of the next item to be printed.

integer-expr

Notes
1. In REPORT program blocks, INFORMIX-4GL calculates the column number by adding integer-expr to the left margin that you set in the OUTPUT section. Otherwise, the column number is counted from the left edge of your screen. 2. If INFORMIX-4GL has already printed past the column specied by integer-expr, INFORMIX-4GL ignores the COLUMN expression. 3. If you use the COLUMN function in a DISPLAY statement, you must specify an integer instead of an integer expression after the COLUMN keyword.

Example
PAGE HEADER PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "CITY", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE ON EVERY ROW PRINT customer_num, COLUMN 12, fname CLIPPED, 1 SPACE, lname CLIPPED, COLUMN 35, city CLIPPED, ", ", state, COLUMN 57, zipcode, COLUMN 65, phone

INFORMIX-4GL Programming

2-29

CURRENT

CURRENT
Overview
The CURRENT function returns a DATETIME value with the date and time of day of the current instant.

Syntax
CURRENT [ rst TO last ]

Explanation
CURRENT is a required keyword.

rst
TO

is a qualier that species the rst eld to be returned. is a required keyword if you specify rst and last. is a qualier that species the last eld to be returned.

last

Notes
1. The value returned is the date and time (from the system clock) when the CURRENT function executes. 2. You can use the CURRENT function in any context in which you can use a DATETIME literal. 3. The rst qualier must specify a eld that is more signicant than or equal to the last qualier. 4. If the function is executed more than once in a statement, identical values may be returned at each point of the call. You cannot rely on CURRENT to provide distinct values each time that it executes in the same statement. 5. INFORMIX-4GL may not execute the CURRENT function in the physical order in which it appears in a statement. You should not use the function to mark the start, the end, or any specic point in the execution of the 4GL statement. 6. If no rst TO last qualiers are specied, the default qualiers are YEAR TO FRACTION(3).

2-30

INFORMIX-4GL Programming

Examples

7. The following qualiers are valid:

Identier YEAR MONTH DAY HOUR MINUTE SECOND FRACTION (n) Qualied Data A number of years. A number of months. A number of days. A number of hours. A number of minutes. A number of seconds. A decimal fraction of a second with n (up to 5) digits of precision. The default precision is 3 digits (thousandths of a second).

Examples
-- SQL statement SELECT prog_title from tv_programs where air_date > CURRENT YEAR TO DAY ATTRIBUTES -- FORM4GL field timestamp = formonly.tmstmp type DATETIME HOUR TO SECOND, default = CURRENT HOUR TO SECOND; PAGE HEADER -- Report control block print column 40, CURRENT MONTH TO MONTH, column 42, "/", column 43, CURRENT DAY TO DAY, column 45, "/", column 46, CURRENT YEAR TO YEAR

Note: The last example would not produce the correct results if its execution spanned midnight.

INFORMIX-4GL Programming

2-31

DATE

DATE
Overview
The DATE function returns a character string that has the format Wed Sep 20 1989 and whose value is the current date.

Syntax
DATE

Explanation
DATE

is a required keyword.

Note
This function reads the current date from the system clock.

Example
The following example displays the current calendar date:
DEFINE p_date CHAR(15) LET p_date = DATE . . . DISPLAY "Today is ", p_date AT 5,14

2-32

INFORMIX-4GL Programming

DATE( )

DATE( )
Overview
The DATE( ) function returns a type DATE value, corresponding to the expression with which you call it.

Syntax
DATE ( expr )

Explanation
DATE

is a required keyword. is a required expression that can be converted to a type DATE value.

expr

Note
The expr is usually of type CHAR, DATETIME, or INTEGER.

Examples
The following example uses DATE to convert a string to a date:
WHERE end_date > DATE("12/13/1989")

This expression returns the 100th day after December 31, 1899:
DATE(100)

INFORMIX-4GL Programming

2-33

DAY( )

DAY( )
Overview
The DAY( ) function returns an integer that represents the day of the month, when you call it with a type DATE argument.

Syntax
DAY ( dtime-expr )

Explanation
DAY

is a required keyword. is a required expression whose value is of type DATE or DATETIME.

dtime-expr

Examples
The rst example extracts the day of the month from a DATETIME literal expression:
DEFINE d_var INTEGER, date_var DATETIME YEAR TO SECOND LET date_var = DATETIME (89-12-09 18:47:32) YEAR TO SECOND LET d_var = DAY(date_var) DISPLAY "The day of the month is: ", d_var USING "##"

The next example uses the DAY ( ) function with the CURRENT function to display the day of the month:
DEFINE dayvar CHAR(2) LET dayvar = DAY(CURRENT) DISPLAY "The day of the month is: ", dayvar USING "##"

2-34

INFORMIX-4GL Programming

EXTEND( )

EXTEND( )
Overview
The EXTEND function adjusts the precision of a DATETIME value.

Syntax
EXTEND ( value [ , rst TO last ] )

Explanation
EXTEND

is a required keyword. is a DATE or DATETIME value (column name, variable, or expression) of any valid precision. is an optional qualier that species the rst eld in the result. (See Note 5.) is a required keyword if you include rst and last qualiers. is an optional qualier that species the last eld in the result. (See Note 6.)

value rst
TO

last

Notes
1. The value can also be a DATETIME literal, or a character string that consists of valid and unambiguous DATETIME values and separators. It cannot be a string constant in DATE format. 2. If no rst TO last qualiers are specied, the default qualiers are YEAR TO FRACTION(3). 3. The rst qualier must specify a eld that is more signicant than or equal to the last qualier. 4. If the value contains elds not specied by the qualiers, the unwanted elds are discarded. 5. If the rst qualier species a eld to the left of (that is, more signicant than) what exists in value, the new elds are lled with values returned by the CURRENT function. 6. If the last qualier species a eld to the right of (that is, less signicant than) what exists in value, the new elds are lled in with constant values.

INFORMIX-4GL Programming

2-35

Examples

A missing MONTH or DAY is lled in with 1, and the missing elds HOUR to FRACTION are lled in with 0. 7. The following qualiers are valid:
Identier YEAR MONTH DAY HOUR MINUTE SECOND FRACTION (n) Qualied Data A number of years. A number of months. A number of days. A number of hours. A number of minutes. A number of seconds. A decimal fraction of a second with n (up to 5) digits of precision. The default precision is 3 digits (thousandths of a second)

8. If an INTERVAL value includes a eld that is not present in a DATETIME or DATE value, you cannot combine the two values with the addition ( + ) or subtraction ( - ) operators. You must rst use the EXTEND function to return an adjusted DATETIME value on which to perform the arithmetic operation.

Examples
In the rst example, the EXTEND function returns the MONTH and DAY elds from a column that contains YEAR, MONTH, and DAY data. In this instance, the YEAR eld is not returned.
SELECT EXTEND(air_date, MONTH TO DAY) FROM tv_programs;

In the next example, the EXTEND function returns a YEAR from CURRENT; it retains the MONTH, DAY, and HOUR values that are already in start_date, and it supplies a MINUTE value of zero.
UPDATE class_sched SET start_date = EXTEND(DATETIME(9-6 9)MONTH TO HOUR, YEAR TO MINUTE);

In the following example, the INTERVAL variable how_old includes elds that are not present in the DATETIME variable t_stamp, so the EXTEND function is required in the expression that calculates the sum of their values.
DEFINE t_stamp DATETIME YEAR TO HOUR DEFINE age DATETIME DAY TO MINUTE DEFINE how_old INTERVAL DAY TO MINUTE LET t_stamp = "1989-12-04 17" LET how_old = INTERVAL (28 9:25) DAY TO MINUTE LET age = EXTEND(t_stamp, DAY TO MINUTE) + how_old 2-36 INFORMIX-4GL Programming

Examples

Appendix J, Working with DATETIME and INTERVAL Data, provides more information on using date and time expressions with arithmetic operators.

INFORMIX-4GL Programming

2-37

LENGTH( )

LENGTH( )
Overview
This function returns the number of bytes in its string argument after deleting all trailing spaces.

Syntax
LENGTH ( str )

Explanation
str is a string constant, CHAR variable, or database column.

Notes
1. In a SELECT or UPDATE statement, with str the identier of a character column, this function returns the number of bytes in the CLIPPED data value. 2. The LENGTH function must be within an SQL statement if str is a database column.

Examples
These statements center a report title on an 80-column page:
LET title = "Invoice for ", fname CLIPPED, " ", lname CLIPPED LET offset = (80 - length(title))/2 PRINT COLUMN offset, title

The next statement retrieves the value in column1 and the length in bytes of the string in column2 (excluding trailing blanks).
SELECT column1, LENGTH(column2) FROM mytable

Note: In INFORMIX-OnLine, this statement supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

2-38

INFORMIX-4GL Programming

MDY( )

MDY( )
Overview
The MDY( ) function returns a type DATE value when you call it with three expressions that evaluate to integers representing the month, day of the month, and year.

Syntax
MDY ( expr1, expr2, expr3 )

Explanation
MDY

is a required keyword. is an expression that evaluates to an integer representing the number of the month (1-12). is an expression that evaluates to an integer representing the number of the day of the month (1-28, 29, 30, or 31, depending on the month). is an expression that evaluates to a four-digit integer representing the year.

expr1 expr2

expr3

Notes
1. Enclose the list of integer expressions expr1, expr2, and expr3 in parentheses, separated by commas. 2. The value of expr3 cannot be the abbreviation for the year. For example, 89 is a year in the rst century.

INFORMIX-4GL Programming

2-39

MONTH( )

MONTH( )
Overview
The MONTH( ) function returns an integer corresponding the month portion of its type DATE or DATETIME argument.

Syntax
MONTH ( dtime-expr )

Explanation
MONTH

is a required keyword. is a required expression of type DATE or DATETIME.

dtime-expr

Notes
1. This function extracts the month from a DATE or DATETIME value, returning an integer m in the range 1 <= m <= 12. 2. The dtime-expr cannot be an INTERVAL argument.

Examples
If the program variable then contains a DATE or DATETIME value, the Boolean expression
MONTH(then) > 9

is TRUE if then is a date in October, November, or December. The values of the year and of the day of the month in expr are ignored.

2-40

INFORMIX-4GL Programming

TIME

TIME
Overview
TIME evaluates as a character string whose value is the current time-of-day from the system clock.

Syntax
TIME

Explanation
TIME

is a required keyword.

Note
The value of TIME is a character string, representing the current time in the format hh:mi:ss, based on a 24-hour clock.

Example
DEFINE p_time char(15) LET p_time = TIME DISPLAY "The time is ", p_time

INFORMIX-4GL Programming

2-41

TODAY

TODAY
Overview
TODAY evaluates as type DATE with a value of the current date, as supplied

by the operating system.

Syntax
TODAY

Explanation
TODAY

is a required keyword.

Example
The following example is from a REPORT program block:
SKIP 1 LINE PRINT COLUMN 15, "FROM: ", begin_date USING "mm/dd/yy", COLUMN 35, "TO: ", end_date USING "mm/dd/yy" PRINT COLUMN 15, "Report run date: ", TODAY USING "mmm dd, yyyy" SKIP 2 LINES PRINT COLUMN 2, "ORDER DATE", COLUMN 15, "COMPANY", COLUMN 35, "NAME", COLUMN 57, "NUMBER", COLUMN 65, "AMOUNT"

2-42

INFORMIX-4GL Programming

UNITS

UNITS
Overview
The UNITS keyword returns an INTERVAL value with one qualier.

Syntax
expr UNITS qualier

Explanation
expr
UNITS

is a number expression. is a required keyword. is the name of an INTERVAL eld.

qualier

Notes
1. The expr can be a program variable, a constant, an expression, a column name, or a function that evaluates to a number. 2. An expression that includes the UNITS keyword can be added to or subtracted from a DATETIME or INTERVAL expression, provided that the UNITS operand follows the arithmetic operator (either + or - ) as the second operand. 3. The qualier can be any one of the following eld keywords:
YEAR HOUR MONTH MINUTE DAY SECOND FRACTION ( n )

Example
LET fortnite = CURRENT + 14 UNITS DAY

INFORMIX-4GL Programming

2-43

USING

USING
Overview
The USING operator species a format for number, MONEY, or DATE expressions. With a number or MONEY expression, you can use USING to line up decimal points or currency symbols, to right- or left-justify numbers, to put negative numbers in parentheses, and to perform other formatting tasks. USING can convert a DATE value to a variety of formats.

Syntax
expr USING "format-string"

Explanation
expr
USING

is a required expression that species what USING is to format. is a required keyword. is a required quoted string that species how USING is to format expr.

format-string

Formatting Number Expressions

The format-string consists of combinations of the following characters: * & # < , . - + ( ) $. The characters - + ( ) $ will oat. When a character oats, INFORMIX-4GL displays multiple leading occurrences of the character as a single character as far to the right as possible, without interfering with the number that is being displayed. Refer to the following list for an explanation of these characters. * & # < , This character lls with asterisks ( * ) any positions in the display eld that would otherwise be blank. This character lls with zeros any positions in the display eld that would otherwise be blank. This character does not change any blank positions in the display eld. You can use this to specify a maximum width for a eld. This character causes numbers in the eld to be left-justied. This character is a literal. USING displays it as a comma (but displays no comma unless there is a number to the left of it).

2-44

INFORMIX-4GL Programming

Explanation

. -

This character is a literal. USING displays it as a period. You can only have one period in a format string. This character is a literal. USING displays it as a minus sign when expr is less than zero, and otherwise as a blank. When you group several minus signs in a row, a single minus sign oats to the rightmost position without interfering with the number being printed. This character is a literal. USING displays it as a plus sign when expr is greater than or equal to zero, and as a minus sign when it is less than zero. When you group several plus signs in a row, a single plus sign oats to the rightmost position without interfering with the number being printed. This character is a literal. USING displays it as a left parenthesis before a negative number. It is the accounting parenthesis that is used in place of a minus sign to indicate a negative number. When you group several parentheses in a row, a single left parenthesis oats to the rightmost position without interfering with the number being printed. This is the accounting parenthesis that is used in place of a minus sign to indicate a negative number. One of these characters generally closes a format string that begins with a left parenthesis. This character is a literal. USING displays it as a dollar sign. When you group several dollar signs in a row, a single dollar sign oats to the rightmost position without interfering with the number being printed.

Refer to the Examples section for examples of formatting number expressions. Since format strings interact with data to produce visual effects, some readers may nd that the examples are easier to follow than the descriptions of format string characters listed previously.

INFORMIX-4GL Programming

2-45

Notes

Formatting DATE Expressions

The format-string for a date can be a combination of the characters m, d, and y, as shown in Figure 2-1. The format-string can also include literals. (See the following examples.)
dd ddd mm mmm day of the month as a 2-digit number (01-31) day of the week as a 3-letter abbreviation (Sun through Sat) month as a 2-digit number (01-12) month as a 3-letter abbreviation (Jan through Dec)

Figure 2-1

yy year as a 2-digit number in the 1900s (00-99) yyyy year as a 4-digit number (0001-9999) Combinations of DATE Format Strings

Notes
1. The format-string must appear between quotation ( " ) marks. 2. Although USING is generally used as part of a DISPLAY or PRINT statement, you can also use it with LET. 3. If you attempt to display a number that is too large for the display eld, INFORMIX-4GL lls the eld with asterisks ( * ) to indicate an overow.

Examples
The following example prints the balance eld using a format string that allows values up to $9,999,999.99 to be formatted correctly.
DISPLAY "The current balance is ", 23485.23 USING "$#,###,##&.&&"

Following is the result of executing this DISPLAY statement with the value 23,485.23:
The current balance is $ 23,485.23

The format string in this example xes the currency symbol. This example also uses the # and & ll characters. The # character provides blank ll for unused character positions, while the & character provides zero lling. This format ensures that even if the number is zero, any positions marked with & will appear as zero, not blank. If dollar signs are used instead of # characters, as in:
DISPLAY "The current balance is ", 23485.23 USING "$$,$$$,$$&.&&"

2-46

INFORMIX-4GL Programming

Examples

the currency symbol oats with the size of the number, so that it appears immediately to the left of the most signicant digit in the display, as shown here:
The current balance is $23,485.23

The following examples show valid conversions for December 25, 1989:
Format String "mmddyy" "ddmmyy" "yymmdd" "yy/mm/dd" "yy mm dd" "yy-mm-dd" "mmm. dd, yyyy" "mmm dd yyyy" "yyyy dd mm" "mmm dd yyyy" "ddd, mmm. dd, yyyy" "(ddd) mmm. dd, yyyy" Formatted Result 122589 251289 891225 89/12/25 89 12 25 89-12-25 Dec. 25, 1989 Dec 25 1989 1989 25 12 Dec 25 1989 Mon, Dec. 25, 1989 (Mon) Dec. 25, 1989

The following example is from a REPORT program block:

ON LAST ROW SKIP 2 LINES PRINT "Number of customers in ", state, " are ", COUNT(*) USING "<<<<<" PAGE TRAILER PRINT COLUMN 35, "page ", PAGENO USING "<<<<"

INFORMIX-4GL Programming

2-47

Examples

The following example is from a more complex REPORT program block and illustrates several different formats:
SKIP 1 LINE PRINT COLUMN 15, "FROM: ", begin_date USING "mm/dd/yy", COLUMN 35, "TO: ", end_date USING "mm/dd/yy" PRINT COLUMN 15, "Report run date: ", TODAY USING "mmm dd, yyyy" skip 2 lines PRINT COLUMN 2, "ORDER DATE", COLUMN 15, "COMPANY", COLUMN 35, "NAME", COLUMN 57, "NUMBER", COLUMN 65, "AMOUNT" BEFORE GROUP OF days SKIP 2 LINES AFTER GROUP OF number PRINT COLUMN 2, order_date, COLUMN 15, company CLIPPED, COLUMN 35, fname CLIPPED, 1 SPACE, lname CLIPPED, COLUMN 55, number USING "####", COLUMN 60, GROUP SUM (total_price) USING "$$,$$$,$$$.&&" AFTER GROUP OF days SKIP 1 LINE PRINT COLUMN 21, "Total amount ordered for the day: ", GROUP SUM (total_price) USING "$$$$,$$$,$$$.&&" SKIP 1 LINE PRINT COLUMN 15, "=====================================================" ON LAST ROW SKIP 1 LINE PRINT COLUMN 15, "======================================================" SKIP 2 LINES PRINT "Total Amount of orders: ", SUM (total_price) USING "$$$$,$$$,$$$.&&" PAGE TRAILER PRINT COLUMN 28, PAGENO USING "page <<<<"

The displays on the next three pages illustrate the full power of the USING operator.

2-48

INFORMIX-4GL Programming

Examples

Format String "#####" "&&&&&" "$$$$$" "*****" "<<<<<"

Data Value 0 0 0 0 0

Formatted Result bbbbb 00000 bbbb$ ***** bbbbb (null string) 12,345 1,234 123 12 12,345 b1,234 bbb123 bbbb12 bbbbb1 bbbbb1 bbbbbb 12,345 01,234 000123 000012 000001 000000 ****** (overflow) $1,234 bb$123 bbb$12 bbbb$1 bbbbb$ 12,345 *1,234 ***123 ****12 *****1 ******

"<<<,<<<" "<<<,<<<" "<<<,<<<" "<<<,<<<" "##,###" "##,###" "##,###" "##,###" "##,###" "##,###" "##,###" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "&&,&&&" "$$,$$$"

12345 1234 123 12 12345 1234 123 12 1 -1 0 12345 1234 123 12 1 0 12345

"$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "$$,$$$" "**,***" "**,***" "**,***" "**,***" "**,***" "**,***"

1234 123 12 1 0 12345 1234 123 12 1 0

Here the character b represents a blank or space.

INFORMIX-4GL Programming

2-49

Examples

Format String "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "##,###.##" "&&,&&&.&&" "&&,&&&.&&" "&&,&&&.&&" "&&,&&&.&&" "$$,$$$.$$" "$$,$$$.$$" "$$,$$$.##" "$$,$$$.##" "$$,$$$.&&" "$$,$$$.&&" "-##,###.##" "-##,###.##" "-##,###.##" "--#,###.##" "---,###.##" "---,-##.##" "---,--#.##" "-##,###.##" "-##,###.##" "-##,###.##" "-##,###.##" "--#,###.##" "---,###.##" "---,-##.##" "---,---.##" "---,---.--"

Data Value 12345.67 1234.56 123.45 12.34 1.23 0.12 0.01 -0.01 -1 12345.67 1234.56 123.45 0.01 12345.67 1234.56 0.00 1234.00 0.00 1234.00 -12345.67 -123.45 -12.34 -12.34 -12.34 -12.34 -1.00 12345.67 1234.56 123.45 12.34 12.34 12.34 12.34 1.00 -.01

Formatted Result 12,345.67 b1,234.56 bbb123.45 bbbb12.34 bbbbb1.23 bbbbb0.12 bbbbbb.01 bbbbbb.01 bbbbb1.00 12,345.67 01,234.56 000123.45 000000.01 ********* (overflow) $1,234.56 $.00 $1,234.00 $.00 $1,234.00 -12,345.67 -bbb123.45 -bbbb12.34 -bbb12.34 -bb12.34 -12.34 -1.00 12,345.67 1,234.56 123.45 12.34 12.34 12.34 12.34 1.00 -.01

Here the character b represents a blank or space.

2-50

INFORMIX-4GL Programming

Examples

Format String "----,---.&&" "-$$$,$$$.&&" "-$$$,$$$.&&" "-$$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "--$$,$$$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "----,--$.&&" "$***,***.&&" "$***,***.&&" "$***,***.&&" "$***,***.&&" "$***,***.&&" "$***,***.&&" "($$$,$$$.&&)" "($$$,$$$.&&)" "($$$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)"

Data Value -.01 -12345.67 -1234.56 -123.45 -12345.67 -1234.56 -123.45 -12.34 -1.23 -12345.67 -1234.56 -123.45 -12.34 -1.23 -.12 12345.67 1234.56 123.45 12.34 1.23 .12 -12345.67 -1234.56 -123.45 -12345.67 -1234.56 -123.45 -12.34 -1.23 -12345.67 -1234.56 -123.45 -12.34 -1.23 -.12

Formatted Result -.01 -$12,345.67 -b$1,234.56 -bbb$123.45 -$12,345.67 -$1,234.56 -bb$123.45 -bbb$12.34 -bbbb$1.23 -$12,345.67 -$1,234.56 -$123.45 -$12.34 -$1.23 -$.12 $*12,345.67 $**1,234.56 $****123.45 $*****12.34 $******1.23 $*******.12 ($12,345.67) (b$1,234.56) (bbb$123.45) ($12,345.67) ($1,234.56) (bb$123.45) (bbb$12.34) (bbbb$1.23) ($12,345.67) ($1,234.56) ($123.45) ($12.34) ($1.23) ($.12)

Here the character b represents a blank or space.

INFORMIX-4GL Programming

2-51

Examples

Format String "($$$,$$$.&&)" "($$$,$$$.&&)" "($$$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "(($$,$$$.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)" "((((,(($.&&)"

Data Value 12345.67 1234.56 123.45 12345.67 1234.56 123.45 12.34 1.23 12345.67 1234.56 123.45 12.34 1.23 .12

Formatted Result $12,345.67 $1,234.56 $123.45 $12,345.67 $1,234.56 $123.45 $12.34 $1.23 $12,345.67 $1,234.56 $123.45 $12.34 $1.23 $.12

Here the character b represents a blank or space.

2-52

INFORMIX-4GL Programming

WEEKDAY( )

WEEKDAY( )
Overview
The WEEKDAY( ) function returns an integer that represents the day of the week, when you call it with a type DATE or DATETIME expression.

Syntax
WEEKDAY ( dtime-expr )

Explanation
WEEKDAY

is a required keyword. is a required expression of type DATE.

dtime-expr

Notes
1. WEEKDAY returns an integer in the range 0-6. Zero represents Sunday, 1 represents Monday, and so on. 2. The dtime-expr cannot be a type INTERVAL argument.

Example
LET tag = WEEKDAY(p_orders.order_date)

INFORMIX-4GL Programming

2-53

YEAR( )

YEAR( )
Overview
The YEAR( ) function returns an integer that represents the year (four digits for 1989) when you call it with a type DATE or DATETIME expression.

Syntax
YEAR ( dtime-expr )

Explanation
YEAR

is a required keyword. is a required expression of type DATE or DATETIME.

dtime-expr

Note
The dtime-expr cannot be an INTERVAL argument.

Example
LET y_var = YEAR(TODAY)

2-54

INFORMIX-4GL Programming

C Functions

C Functions
INFORMIX-4GL programs can call C language functions. To provide a transparent function-calling mechanism, INFORMIX-4GL requires that C functions follow a calling convention that allows data to be passed between the INFORMIX-4GL program and the C function.

This calling convention that is described in this section applies to both the C Compiler Version and Rapid Development System implementations of INFORMIX-4GL. If you have the Rapid Development System, see also the sectionRDS Programs That Call C Functions in Chapter 1, which describes the additional procedures that are required to compile and run such programs. The convention uses a stack, which is a data structure that can be accessed in a predened way by both INFORMIX-4GL programs and C functions. You can perform two classes of operations on a stack: push pop to add a variable to the stack to retrieve a variable from the stack

The stack acts as a LIFO (last-in, rst-out) queue. The variable added to the stack by the last push is the next variable to be removed from the stack if you do a pop. The next page lists functions that are provided with INFORMIX-4GL to perform pushes and pops on specic data types. Consider the following INFORMIX-4GL statement:
CALL myfunc (a,b,c)

Part of the calling convention is that function arguments are pushed from left to right onto the stack. INFORMIX-4GL automatically pushes the variables a, b, and c onto the stack, in that order. Another part of the calling convention requires INFORMIX-4GL to automatically pass the number of calling parameters as the only real argument to the C function. This tells the C function how many values to pop. The C functions designed to work with INFORMIX-4GL must obey the calling convention by complementing the actions of INFORMIX-4GL. All compatible C functions have only one argument, which is the number of parameters that INFORMIX-4GL placed on the stack. You use this argument to pop the calling parameters. INFORMIX-4GL supplies the following library of functions to assist this process.

INFORMIX-4GL Programming

2-55

C Functions

Popping Functions popint(&i) popshort(&s) poplong(&l) popo(&f) popdub(&d) popquote(str, len) popdec(&dm) popdtime(&dt, qual) popinv(&inv, qual)

Pushing Functions retint(i) retshort(s) retlong(l) reto(&f) retdub(&d) retquote(str) retdec(&dm) retdtime(&dt) retinv(&inv)

Argument Types int i; short s; long l; oat f; double d; char *str; int len; dec_t dm; dtime_t dt; int qual; intrvl_t inv; int qual;

Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information. Here len is the buffer size of the string to which str points, and qual is the qualier of the DATETIME or INTERVAL value that will be received by destination variable dt or inv. Your rst step in a C function is to pop all the arguments in the reverse order from the order in the call. If the call is to myfunc, you must rst pop c, and then b, and nally a. You must use the library function that is appropriate for the data type of the receiving variable. After the function is called, INFORMIX-4GL restores the stack pointer to its original state. To return values from the C function to the INFORMIX-4GL program, you must push the values onto the stack. They must be pushed in the same order as they appear in the RETURNING clause of your INFORMIX-4GL statement. For example, if the statement is
CALL ... RETURNING x, y

you must push x before pushing y within your C function. You must use the library function that matches the data type to execute the push. The last statement that your C function executes must be a return, where the only parameter is the number of variables that are being returned. Make sure that the variables returned by your C function match, both in number and in data type, the argument list in the RETURNING clause of the INFORMIX-4GL statement. If you do not return the correct data types, your program can execute unpredictably. Failure to return the expected number of arguments causes an error.

2-56

INFORMIX-4GL Programming

Examples

When using the C library functions, you must be aware of the following factors:

If you use the retquote(str) function, you must null-terminate the string. The string str in popquote will be null-terminated, so you should allow
for that in the value of m.

The dec_t structure is dened in Appendix F, along with a number of

useful functions that you can use to convert DECIMAL variables to other number data types and back again within your C functions. (They are not necessary within an INFORMIX-4GL program, since their functionality is already supported by INFORMIX-4GL.)

Examples
The rst example (which only schematically represents actual C code) shows the basic structure for C functions that you can call from an INFORMIX-4GL program.
myfunc(n) int n; { /* n specifies how many 4gl parameters * were passed by the calling 4gl statement */ test that the value of n is correct pop n 4gl parameters in reverse order, right to left ... code push x returning 4gl parameters, left to right return(x) /* must return the number x, specifying how many 4gl * variables are "RETURNING" */

INFORMIX-4GL Programming

2-57

Examples

The following INFORMIX-4GL program calls the C language function sndmsg, which converts a string into EBCDIC and sends it to a remote computer. Two arguments are explicitly passed to the function: the source string and its length. INFORMIX-4GL automatically passes the number of arguments to the function.
MAIN DEFINE chartype CHAR(80), msg_status INTEGER, return_code INTEGER LET chartype = "234" # # # # # sndmsg requires two arguments and returns two arguments, as defined by the C language function. You must ensure that the order and data types of all arguments are compatible between the 4gl calling program and the called function. CALL sndmsg(chartype, 4) RETURNING msg_status, return_code IF return_code <> 0 THEN DISPLAY "Error code: ", return_code END IF DISPLAY msg_status END MAIN

The function sndmsg checks that the correct number of arguments are passed. INFORMIX-4GL cannot guarantee recovery of the stack if a function is called with the wrong number of arguments, since that is a failure to follow the calling convention between INFORMIX-4GL and C functions. The sndmsg function terminates the program if the wrong number of arguments is passed.

2-58

INFORMIX-4GL Programming

Examples

If the correct number of arguments is passed, sndmsg pops the arguments from the stack, using the library functions appropriate for the data type. An annotated listing of the sndmsg program follows:
#include "stdio.h" #include "decimal.h" sndmsg(nargs) /* 4gl syntax is CALL sndmsg (input,len) RETURNING int nargs; { char int int input[80]; msg_number; len, retcode; /* 4gl and C function must agree on data */ /* types and the order that arguments are */ /* placed on the stack */ msg_number, retcode */

/* 4gl passes the number of arguments as an integer */

/* Check that the correct number of arguments are passed */ if (nargs != 2) { fprintf (stderr, "sndmsg: wrong number of arguments"); exit(1); /* No recovery from this error */ } /* Pop rightmost argument */ popint(&len); /* Pop next argument popquote(input,len); /* Finished with function calling convention */ /* Start function processing */ msg_number =-1; retcode = cvtebcd (&input, len); /* user-written function */ if (retcode != 0) msg_number = sndrmt (input,len); /* user-written function */ /* Finished processing */ /* Return (push) leftmost argument */ retint(msg_number); /* Return next argument */ retint(retcode); /* Finished returning arguments */ /* Return from function giving number of arguments */ return(2); } */

To return values to the program, the C function uses appropriate push functions for the data type and pushes return arguments onto the stack from left to right. The last statement executed by the function returns the number of
INFORMIX-4GL Programming 2-59

Examples

arguments, which is two for sndmsg. A discrepancy between the number of return arguments in the function and the number of arguments expected by the program results in an error.

2-60

INFORMIX-4GL Programming

Chapter

Using SQL
Chapter Overview 5 Relational Databases SQL Identiers 6 Owner Naming Database Data Types 7 8 10 5

3
14

SQL Statement Summary Data Denition 11 12

Data Manipulation

Cursor Management 13 SELECT Cursors 13 Associating a Cursor with a SELECT Statement Retrieving and Processing Rows 15 The SCROLL Cursor 20 The Cursor WITH HOLD 23 INSERT Cursors 25 Dynamic Management 28 Preparing Statements 29 Statements That Require No Input 30 Statements That Require Input for Values 30 Statements That Require Input for SQL Identiers 32 Executing PREPAREd Statements 33 The EXECUTE Statement 33 Running PREPAREd SELECT Statements 35 Running PREPAREd INSERT Statements 37 Preparing Multiple SQL Statements 38 The FREE Statement 39

Data Access

40 41

User Status and Privileges

Data Integrity 42 Transactions 42 Databases Without Transactions 43 Databases with Implicit Transactions 43 Databases with Explicit Transactions 44 Using Transactions 44 Transaction Log File Maintenance 45 Audit Trails 45 Creating an Audit Trail 46 Recovering a Table 46 Comparison of Transactions and Audit Trails 47 Locking 47 Row-Level Locking 48 Row-Level Locking in Transactions Table-Level Locking 49 Wait for Locked Row 50 Indexing Strategy 50 Query Optimizer 52 Auto-Indexing 52 Clustered Indexes 52 NULL Values 53 Default Values 54 The NULL in Expressions 54 The NULL in Boolean Expressions 55 The NULL in WHERE Clauses 55 The NULL in ORDER BY Clauses 56 The NULL in GROUP BY Clauses 56 The NULL Keyword in INSERT and UPDATE Statements Views 57 Creating and Deleting Views 58 Querying Through Views 58 Modifying Through Views 59 Privileges with Views 60 Data Constraints Using Views 60

49

57

3-2

Using SQL

Outer Joins

61 62

Table Access by ROWID SQLCA Record 63

TODAY, CURRENT, and USER Functions

65

Using SQL

3-3

3-4

Using SQL

Chapter Overview
Informix Software, Inc. has developed an implementation of SQL that extends the Structured Query Language (SQL) developed by IBM. The Informix Software additions to the language permit you to change databases, to change the names of tables and columns, and to increase the functionality of ANSI standard SQL statements. In the family of Informix Software database products, SQL plays several roles. In INFORMIX-SQL, SQL is both the interactive query language and the language you use to choose the data for ACE, the INFORMIX-SQL report-writing program. You can read about these uses of SQL in the INFORMIX-SQL User Manual. In INFORMIX-ESQL/C, SQL is the database query language that you embed in C programs to create an application. In INFORMIX-4GL, SQL statements are combined with those described in Chapter 2 to form an almost seamless fourth-generation language. This chapter describes SQL and gives an overview of its statements. The full syntax and rules governing SQL statements are located in Chapter 7 of the INFORMIX-4GL Reference Manual.

Relational Databases
SQL statements create and manipulate relational databases. A relational

database consists of one or more tables that, in turn, are constructed of rows and columns. Each row contains a specic set of column values. Databases are created as subdirectories of the current directory. The name of the directory is the database name with the extension .dbs. The database subdirectory contains 11 system catalog tables that dene the database dictionary. It also contains the tables that constitute the database. Each of these tables is represented by data les and index les, with the extensions .dat and .idx, respectively. The system catalogs are described in Appendix B.

Using SQL

3-5

SQL Identiers

You have the option of specifying a MODE ANSI database. A database created or started as MODE ANSI supports implicit transactions and enforces ownernaming. (See the section Data Integrity for more information about transactions in a MODE ANSI database. See the section Owner Naming for more information about owner-naming.)
INFORMIX-4GL provides several ways to check for Informix extensions to the ANSI standard for SQL syntax in your programs:

If you use the -ansi ag in the command line that invokes the 4GL
compiler, you receive a compile-time warning, in the form of messages to a diagnostic le, if the program includes Informix extensions to the ANSI standard for SQL syntax.

INFORMIX-4GL issues a run-time warning by setting the character

SQLCA.SQLAWARN [6] to W, if a program executes a statement that includes an Informix extension to ANSI syntax, and the DBANSIWARN environment variable is dened (as described in Appendix C.) See INFORMIX-4GL Extensions to ANSI Syntax in Chapter 7 for a list of the Informix extensions to the ANSI standard.

SQL Identiers
An SQL identier is the name of an object. It can consist of letters, numbers, and underscores ( _ ). The rst character must be a letter. Unless otherwise indicated, an identier can have from one to 18 characters. Database Table A database name is an identier that can have from one to 10 characters. A table name is an identier that must be unique within the database. (In a MODE ANSI database, the owner and table combined must be unique within the database.) A column name is an identier that must be unique within a table; there can be duplicate column names within a database. When column names within different tables are not unique, use the notation table.column to specify the intended column. If you intend to dene an INFORMIX-4GL record like a table, the rst 8 characters of each column name in the table must be unique within the table.

Column

If there is an ambiguity because an INFORMIX-4GL identier and an SQL identier are the same, INFORMIX-4GL assumes that the identier refers to a 4GL program variable and not to the SQL object. If you want to override
3-6 Using SQL

Owner Naming

this default assignment, prex the SQL identier with an at sign ( @ ). For example, if lname is dened as a program variable, but you wish to refer to the database column of the same name, use @lname for the column name:
SELECT @lname INTO lname FROM customer

Owner Naming
In a database created as MODE ANSI, the name of each object (table, view, index, synonym, and constraint) is qualied by the name of the owner of the object. The combined owner.object must be unique within the database. The following rules apply to the naming of an object:

owner is the login name of the owner of the object. The name must begin
with a letter. It can contain underscores, letters, and numbers, and can be up to 8 characters long. Alternatively, the name can be a quoted string. This allows you to preserve uppercase characters in user names or to include a user name in which the rst character is a digit. The quoted string can be up to 8 characters long.

object is a valid identier for a table, view, index, synonym, or constraint.

The identier must begin with a letter. It can contain underscores, letters, and numbers, and can be up to 18 characters long. The format for naming an object in an SQL statement is as follows:
[owner. ] object

An object receives its owner when it is CREATEd. You cannot change the ownership of an object. By default, ownership is assigned to the individual who creates the object. However, a user with database administrator (DBA) privilege can create an object and assign ownership of the object to another user. In a database created as MODE ANSI, you must specify owner when referring to an object created by another user. As with non-MODE ANSI databases, you may specify owner when referring to your own objects. In the following example, the UPDATE statement modies rows in the stock table owned by the user james:
UPDATE james.stock SET price = price * 1.05

Using SQL

3-7

Database Data Types

Quoted strings allow you to retain case sensitivity when case is important. In the following examples, the SELECT statements retrieve rows from different tables:
SELECT * FROM "Smith".stock SELECT * FROM Smith.stock

Note that "Smith" is in quotes in the rst SELECT statement but not in the second. Because of the quotes, the case distinction is preserved in the rst SELECT; therefore, the rst SELECT retrieves rows from the Smith.stock table while the second SELECT retrieves rows from the smith.stock table. The engine assumes an object is owned by the user if you do not include the owner prex. As the owner of the system catalog tables is informix, you must include the owner name informix when querying each system catalog. You do not have to supply owner names when working with a non-MODE ANSI database. However, if you specify the owner along with the object name, the engine will check for the accuracy of the owner name. Note: In a MODE ANSI database, you receive an error if you do not use the owner.object naming convention to refer to an object owned by another user. If you start a database as MODE ANSI, you must modify existing queries that reference a table, view, or synonym owned by another user to include the owner prex.

Database Data Types

You must assign a data type to every column in the database. (See the CREATE TABLE statement in Chapter 7). Except for the SERIAL data type, the SQL data types are identical to the corresponding 4GL data types that were dened in Chapter 2. The valid SQL data types are as follows:
CHAR [(n)] CHARACTER SMALLINT INTEGER INT DECIMAL [(m[,n])]

is a character string of length n (where 1 n 32,511). If you do not specify n, CHAR(1) is assumed. is a synonym for CHAR. is a whole number from -32,767 to +32,767. is a whole number from -2,147,483,647 to +2,147,483,647. is a synonym for INTEGER. is a decimal oating point number with m ( 32) signicant digits (the precision) and n ( m) digits right of the decimal point (the scale). When you give values for both m and n, the decimal variable has xed-point arithmetic. All numbers with an absolute

3-8

Using SQL

Database Data Types

value less than 0.5 10-n have the value zero. The largest absolute value of a DECIMAL variable that can be stored without an error is 10m-n - 10-n. The second parameter is optional and, if missing, the variable is treated as a oating decimal. DECIMAL(m) variables have a precision of and a range in absolute value from 10-128 to 10126 If no parameters are designated, DECIMAL is treated as DECIMAL(16), a oating decimal.
DEC NUMERIC SMALLFLOAT

is a synonym for DECIMAL. is another synonym for DECIMAL. is a oating-point number corresponding to the oat C data type. The range of values for a SMALLFLOAT data type is the same as the range of values for the C oat data type on your machine. is a synonym for SMALLFLOAT. is a oating-point number corresponding to the double C data type. The range of values for a FLOAT data type is the same as the range of values for the C double data type on your machine. You can use n (where n is a whole number between 1 and 14) to specify the precision of a FLOAT data type. INFORMIX-4GL does not use the precision, however. (The optional precision parameter is provided for compatibility with ANSI standards.)

REAL FLOAT [(n)]

DOUBLE PRECISION MONEY [(m [,n] )]

is a synonym for FLOAT. can take two parameters like the DECIMAL data type. The limitation on values for columns of type MONEY (m, n) is the same for columns of type DECIMAL (m, n). The type MONEY (m) is dened as DECIMAL (m, 2) and, if no parameter is given, MONEY defaults to DECIMAL (16, 2). Regardless of the number of parameters, the data type MONEY is always treated as a xed decimal number. is a sequential integer assigned automatically by
INFORMIX-4GL. You can assign an initial value n.

SERIAL [ (n) ]

The default starting integer is 1.

DATE

is a date entered as a character string in one of the formats described in Chapter 2, and stored as an integer number of days since December 31, 1899.
Using SQL 3-9

SQL Statement Summary

DATETIME rst TO last

stores a moment in time with the precision rst to last. A DATETIME column is entered as a character string in one of the formats described in Chapter 2, recording the value of a calendar date and time of day. It is stored internally as a DECIMAL number, whose digits represent a contiguous sequence of the following elds: YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and FRACTION(n) of a second. DATETIME is described in greater detail in Appendix J. stores a span of time with the precision rst to last. An INTERVAL column is entered as a character string in one of the formats described in Chapter 2, recording the value of the difference between two DATETIME values. It is stored internally as a DECIMAL number, whose digits represent values of the elds from rst to last. An INTERVAL column consists of a contiguous sequence of one of the following two lists of elds: either YEAR and MONTH; or else DAY, HOUR, MINUTE, SECOND, and FRACTION(n) of a second. INTERVAL is described in greater detail in Appendix J.

INTERVAL rst TO last

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

SQL Statement Summary

Six different types of SQL statements are used with INFORMIX-4GL:

Data denition Data manipulation Cursor management Dynamic management Data access Data integrity

3-10

Using SQL

Data Denition

Data Denition
Data denition statements include those that create and drop a database and its tables, views, and indexes, modify tables, indexes, and columns, or rename tables and columns. Of this list, only the DATABASE statement is required before manipulating the data of an existing database or dening program variables LIKE columns in the database. creates a database directory, sets up the system catalogs, and CREATE makes the new database the current database. There can be no DATABASE more than one current database at any time.
DATABASE CLOSE DATABASE

selects a database and makes it the current database. There can be no more than one current database at any time. closes the current database les and leaves no database current. The only SQL statements permitted when there is no current database are: CREATE DATABASE DATABASE DROP DATABASE START DATABASE deletes all tables, indexes, and system catalogs. If no other les are present in the database subdirectory, the subdirectory is also deleted. creates a table and denes the columns and their data types. adds or drops columns and constraints from a table, and modies data types of existing columns. changes the name of a table, replacing the old name with the new name in the system catalogs. deletes all data and indexes for a table and erases its entry in the system catalogs. denes a table selected from rows and columns of existing tables and views. As the underlying tables change, so does the view built on them. See the section Views later in this chapter for more information about views. deletes the denition of the view from the system catalogs, along with any views dened in terms of the one that is dropped. The underlying tables are unaffected. denes an alternative name for a table or a view. For INFORMIX-4GL programs, the creator of the synonym is the user who runs the program that creates the synonym.
Using SQL 3-11

DROP DATABASE CREATE TABLE ALTER TABLE RENAME TABLE DROP TABLE CREATE VIEW

DROP VIEW CREATE SYNONYM

Data Manipulation

DROP SYNONYM RENAME COLUMN CREATE INDEX ALTER INDEX DROP INDEX UPDATE STATISTICS

deletes a synonym from the system catalogs. changes the name of a column, replacing the old name with the new name in the system catalogs. creates an index on one or more columns of a table. See the section Indexing Strategy later in this chapter for more information on indexes. clusters a table in the order of an existing index or releases an index from the cluster attribute. deletes an existing index, removing it from the system catalogs. updates the system catalogs by determining and inserting the number of rows in the indicated tables. INFORMIX-4GL uses this information in optimizing queries but does not automatically update the system catalogs after each INSERT or DELETE.

Data Manipulation
The data manipulation statements are the most frequently used SQL statements:
DELETE INSERT LOAD SELECT UNLOAD UPDATE

deletes one or more rows from a table. adds one or more rows to a table. inserts rows from an operating system le. retrieves data from one or more tables. copies rows to an operating system le. modies the data in one or more rows of a table.

SELECT is the most important and the most complex SQL statement.

Although its syntax is dened in detail in Chapter 7, the following examples illustrate its use:
SELECT lname, company INTO p_lname, p_company FROM customer WHERE customer_num = 101

3-12

Using SQL

Cursor Management

This statement queries the customer table and returns the single row for which the customer number is 101. From that row, it selects and places the values in the columns corresponding to the last name and company name of the contact in the program variables p_lname and p_company.
SELECT @quantity, @total_price INTO quantity, total_price FROM items WHERE order_num = 1001

This example shows another SELECT statement that returns a single row. In this example, the program variables quantity and total_price have the same identier as the corresponding columns in the items table. There is no conict here, since the prex @ distinguishes the column name from the program variable. A SELECT statement that returns a single row is called a singleton SELECT statement and can stand alone. The section Cursor Management that follows describes how to handle SELECT statements that return more than one row.

Cursor Management
INFORMIX-4GL provides two functional types of cursors:

A SELECT cursor, which you must use to handle a SELECT statement that
returns more than one row.

An INSERT cursor, which you can use to insert rows into the database as
a block. The section SELECT Cursors describes how to associate a cursor with a SELECT statement and gives examples of the uses of the SELECT cursor. The section INSERT Cursors explains how to associate a cursor with an INSERT statement and describes the advantages of using an INSERT cursor.

SELECT Cursors
When a SELECT statement returns exactly one row, the values returned to the program variables are unambiguous. However, when more than one row can be returned, it is necessary to have a device to distinguish one row from another. This device is called a cursor.

Using SQL

3-13

SELECT Cursors

The set of rows returned by a SELECT statement is called the active set for the statement. Within an INFORMIX-4GL program, you can work with only one row of the active set at a time. This row is called the current row, and it is referenced by a cursor. A cursor can be in one of two states: open or closed. When a SELECT cursor is in an open state, it is associated with an active set and can point to the current row, between two rows, before the rst row, or after the last row. When it is in a closed state, the cursor is no longer associated with an active set, although it remains associated with the SELECT statement. The following sections describe how to use the cursor management statements to process rows returned by a SELECT statement. (For complete information on the syntax of each statement, see Chapter 7.)

Associating a Cursor with a SELECT Statement

You use the DECLARE statement to name a cursor and to associate it with a SELECT statement. In the DECLARE statement, you specify the type of cursor that you want to use:

A regular (or non-scrolling) cursor allows rows to be retrieved from the

active set in consecutive order. You also DECLARE a regular cursor when you plan to delete or update the current row in the active set.

The SCROLL cursor allows rows to be retrieved from the active set in random order.

A regular or SCROLL cursor can be specied as WITH HOLD. Unlike regular or SCROLL cursors that are not WITH HOLD, a cursor DECLAREd as WITH HOLD is not closed at the end of a transaction. For example, the following DECLARE statement associates a SCROLL cursor named q_curs with a SELECT statement that retrieves all the rows from the customer table:
DECLARE q_curs SCROLL CURSOR FOR SELECT * FROM customer

The following DECLARE statement associates a non-scrolling cursor with a SELECT statement that retrieves customer rows based on a value that the user supplies for column last name:
PROMPT "Enter a last name: " FOR last_name

DECLARE cust_curs CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name

3-14

Using SQL

SELECT Cursors

A cursor name has meaning only from the point at which it is DECLAREd to the end of the source-code le. The DECLARE statement for a cursor must physically appear before any statement that refers to it. For example, the following program will not compile because the DECLARE statement for q_curs appears after the FOREACH statement that refers to it. (See the following section, Retrieving and Processing Rows for more information about FOREACH.
DATABASE stores MAIN DEFINE p_customer RECORD LIKE customer.* OPEN FORM custform FROM "customer" DISPLAY FORM custform CALL get_curs() -- INCORRECT FOREACH q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* . . . END FOREACH END MAIN FUNCTION get_curs() DECLARE q_curs CURSOR FOR SELECT * FROM customer END FUNCTION

Retrieving and Processing Rows

Once you have DECLAREd a cursor for a SELECT statement, you can use either the FOREACH statement or the OPEN, FETCH, and CLOSE statements to retrieve and process the rows specied by the SELECT statement.

Using SQL

3-15

SELECT Cursors

The FOREACH Statement

Using the FOREACH statement, you can select rows and execute a series of statements for each row returned by a query. The following example uses a FOREACH statement to retrieve and display rows in the customer table:
PROMPT "Enter a last name: " FOR last_name DECLARE q_curs CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name FOREACH q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* . . . END FOREACH

When INFORMIX-4GL encounters the FOREACH statement in this example, it runs the query and repeatedly performs the following operations until the active set is exhausted:

Retrieves the next row from the active set and stores it in the p_customer
record

Displays the values in the p_customer record on a screen form Executes all additional statements within the FOREACH loop
You can use the FOREACH statement when you want to retrieve the rows specied by a SELECT statement and then process them in consecutive order. You can use the FOREACH statement with a regular cursor, a SCROLL cursor, or a cursor WITH HOLD.

The OPEN, FETCH, and CLOSE Statements

You can use the OPEN, FETCH, and CLOSE statements when you need to explicitly control the behavior of a cursor:
OPEN

puts the cursor in an open state with regard to the SELECT statement. The OPEN statement causes the SELECT statement to run with the current program variables and leaves the cursor pointing just before the rst row of the resulting active set. While the cursor is in an open state, subsequent changes to any program variables that appear in the SELECT statement associated with the cursor do not affect the active set. advances the cursor to the specied row (either FIRST, LAST, NEXT, PRIOR or PREVIOUS, ABSOLUTE n, or RELATIVE m) and retrieves

FETCH

3-16

Using SQL

SELECT Cursors

the values from that row. If a FETCH statement moves the cursor before the rst row or after the last row, the error variable status has the value NOTFOUND (= 100), as does the SQLCODE component of the SQLCA record. (See the section SQLCA Record later in this chapter for more information.) NOTFOUND indicates that either end of the active list has been reached.
CLOSE

puts the cursor in a closed state and releases the active set. No statements referring to the cursor, other than OPEN, are operative.

For example, consider the following DECLARE statement:

DECLARE x CURSOR FOR SELECT order_num, order_date FROM orders WHERE paid_date IS NULL AND ship_date > p_date FOR UPDATE OF paid_date

This statement names a cursor x and associates it with the SELECT statement that follows the FOR keyword. The SELECT statement returns the order number and order date for those unpaid orders whose shipping date was later than the date in the program variable p_date. The statement also enables a future UPDATE statement to modify the paid_date column. The DECLARE statement does not perform the query; it simply assigns the cursor to the SELECT statement.
OPEN x

When you execute the OPEN statement later in your program, the Boolean expression in the WHERE clause of the SELECT statement uses the value of the variable p_date at the time of the OPEN statement.
FETCH x INTO order_num, order_date

The FETCH statement retrieves the rows of the active set, moves x to point to the rst row, and assigns to the program variables order_num and order_date the values of the columns order_num and order_date in the rst row:
UPDATE orders SET paid_date = TODAY WHERE CURRENT OF x

The UPDATE statement substitutes the current date (returned by the TODAY function) for the existing NULL value of paid_date in the current row (that is, the rst row) of the active set. The cursor remains pointing to the rst row:
CLOSE x

Using SQL

3-17

SELECT Cursors

The cursor x is now put into a closed state, and the active set is effectively dissolved. An immediate FETCH statement would be an error because a cursor in a closed state cannot point to anything. If, at a later time, you should execute the statement
OPEN x

the cursor x would be put back into an open state with a new active set that depends on the value of the program variable p_date when the OPEN statement was executed.

Deleting or Updating the Current Row

You can use special forms of the DECLARE, DELETE, and UPDATE statements to delete or update the current row in an active set. You cannot use a SCROLL cursor to process the rows returned by a SELECT statement, and the SELECT statement cannot include an ORDER BY clause. To delete a row in an active set, you must include a FOR UPDATE clause in the DECLARE statement for a non-SCROLLing cursor, and also specify a WHERE CURRENT OF clause in a subsequent DELETE statement. The following program fragment is an example.
-- Prompt user, then read name from terminal. PROMPT "Enter a last name: " FOR last_name DECLARE q_curs CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name FOR UPDATE FOREACH q_curs INTO IF status <> 0 EXIT FOREACH cust_rec

-- Display customer values here. . . . PROMPT "Do you want to delete this customer (y/n) ? " FOR answer IF answer = "y" DELETE FROM customer WHERE CURRENT OF q_curs END IF END FOREACH . . .

3-18

Using SQL

SELECT Cursors

The cursor remains between rows after a DELETE WHERE CURRENT OF statement is executed. This means that you cannot refer to the cursor in another DELETE or UPDATE statement until you use a FETCH statement to advance the cursor to the next row. You can update the current row if you include a FOR UPDATE clause in the DECLARE statement for a non-SCROLLing cursor, and a WHERE CURRENT OF clause in a subsequent UPDATE statement. The following example allows the user to update the address information in the current row:
DECLARE q_curs CURSOR FOR SELECT * FROM customer FOR UPDATE

FOREACH q_curs INTO cust_rec IF status <> 0 EXIT FOREACH -- Display customer values here. . . . PROMPT "Do you want to change the customers address (y/n) ?" FOR answer IF answer = "y"

-- Input the new values here. . . . UPDATE customer SET address1 = cust_rec.address1, address2 = cust_rec.address2, city = cust_rec.city, state = cust_rec.state, zipcode = cust_rec.zipcode WHERE CURRENT OF q_curs . . . END IF END FOREACH

If you specify one or more columns in the FOR UPDATE clause of the DECLARE statement, you can only update those columns in a subsequent UPDATE WHERE CURRENT OF statement. If you do not list columns in a FOR UPDATE OF column-list clause, you can update any column retrieved in the query.

Using SQL

3-19

SELECT Cursors

The following example allows the user to update the fname and lname columns of the current row:
BEGIN WORK DECLARE q_curs CURSOR FOR SELECT * FROM customer FOR UPDATE OF fname, lname FOREACH q_curs INTO cust_rec IF status <> 0) EXIT FOREACH -- Display customer values here. . . . PROMPT "Do you want to change the name (y/n) ? " FOR answer IF answer= "y" -- Input the new customer values here. . . . UPDATE customer SET fname = cust_rec.fname, lname = cust_rec.lname WHERE CURRENT OF q_curs END IF END FOREACH

The position of the cursor does not change after an UPDATE WHERE
CURRENT OF statement is executed.

If your database has a transaction log but is not MODE ANSI, you must issue a BEGIN WORK statement before you OPEN a cursor DECLAREd FOR UPDATE that is not WITH HOLD. This requirement does not apply to cursors DECLAREd WITH HOLD, or to cursors that are not FOR UPDATE. In a MODE ANSI database, this distinction disappears because INFORMIX-4GL automatically includes all statements within transactions. You must not use the BEGIN WORK statement in the previous example with a MODE ANSI database. (The section Data Integrity later in this chapter describes transactions.)

The SCROLL Cursor

When you need to process the rows returned by a SELECT statement in random order, you must DECLARE a SCROLL cursor and use the OPEN, FETCH, and CLOSE statements.
3-20 Using SQL

SELECT Cursors

When you initially FETCH a row with a SCROLL cursor, all the rows in the active set up to and including the FETCHed row are placed in a temporary le and remain there until you close the cursor. If you then FETCH the same row or any row prior to it, INFORMIX-4GL retrieves the row from the temporary le instead of from the database. The temporary le allows you to retrieve rows in a random order. It also means, however, that subsequent changes to the database may not be reected in the active set used by a SCROLL cursor. Thus, you cannot DECLARE a SCROLL cursor FOR UPDATE. Instead, you must DECLARE FOR UPDATE a regular cursor or a cursor WITH HOLD when you plan to perform a subsequent UPDATE WHERE CURRENT OF or DELETE WHERE CURRENT OF action. The following example shows how to use a SCROLL cursor and various cursor management statements to retrieve and display rows in the customer table.
MAIN . . . DECLARE q_curs SCROLL CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name OPEN q_curs FETCH FIRST q_curs INTO p_customer.* IF status = NOTFOUND THEN CALL mess("No customers found.") ELSE DISPLAY BY NAME p_customer.* CALL viewcust() END IF CLOSE q_curs . . . END MAIN

The MAIN program block includes the following statements:

The DECLARE statement associates a SCROLL cursor called q_curs

with the SELECT statement that retrieves rows from the customer table. (The program uses a SCROLL cursor so that rows specied by the SELECT statement can be retrieved in random order.)

The OPEN statement runs the SELECT statement with the current value of
last_name and leaves the cursor pointing just before the rst row of the active set.

The FETCH FIRST statement attempts to retrieve the rst row of the
active set.
Using SQL 3-21

SELECT Cursors

The IF statement displays a message indicating that the active set is

empty if the value of the status variable is NOTFOUND. Otherwise, the program displays the rst row on a screen form and calls a function that allows the user to browse through the rows in the active set.

The CLOSE statement releases the active set after all rows have been
processed. The viewcust function displays a menu that lets the user view the rows in the active set:
FUNCTION viewcust() MENU "BROWSE:" COMMAND "Next" "View the next customer in the list" FETCH NEXT q_curs INTO p_customer.* IF status = NOTFOUND THEN CALL mess("No more customers in this direction.") FETCH LAST q_curs INTO p_customer.* END IF DISPLAY BY NAME p_customer.* COMMAND "Previous" "View the previous customer in the list" FETCH PREVIOUS q_curs INTO p_customer.* IF status = NOTFOUND THEN CALL mess("No more customers in this direction.") FETCH FIRST q_curs INTO p_customer.* END IF DISPLAY BY NAME p_customer.* COMMAND "First" "View the first customer in the list" FETCH FIRST q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* COMMAND "Last" "View the last customer in the list" FETCH LAST q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* COMMAND "Exit" "Leave the menu" EXIT MENU END MENU END FUNCTION

This function consists of a MENU statement that contains the following COMMAND clauses: Next includes a FETCH NEXT statement that attempts to retrieve the next row of the active set. The IF statement returns the cursor to the last row and displays a message if the value of the status variable indicates that the cursor has moved beyond the last row of the active set. The DISPLAY BY NAME statement displays on the screen the row retrieved by the appropriate FETCH statement.

Previous includes a FETCH PREVIOUS statement that attempts to retrieve the previous row of the active set. The IF statement returns the cur3-22 Using SQL

SELECT Cursors

sor to the rst row, and displays a message if the value of the status variable indicates that the cursor has moved beyond the rst row of the active set. The DISPLAY BY NAME statement displays on the screen the row retrieved by the appropriate FETCH statement. First Last Exit includes a FETCH FIRST statement that retrieves the rst row in the active set and displays it on the screen. includes a FETCH LAST statement that retrieves the last row in the active set and displays it on the screen. includes an EXIT MENU statement that terminates the MENU statement.

All FETCH statements except the default FETCH NEXT statement require that you rst DECLARE a SCROLL cursor. The default FETCH statement works with all cursors. Note: When you open a cursor that identies a SELECT statement containing a program variable, INFORMIX-4GL runs the SELECT statement with the current value of the program variable. In the following example, the active set produced by the rst OPEN statement differs from the active set produced by the second OPEN statement because the value of last_name changes from Baxter to Grant:
LET last_name = "Baxter" DECLARE q_curs SCROLL CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name OPEN q_curs . . . CLOSE q_curs LET last_name = "Grant" OPEN q_curs

The Cursor WITH HOLD

In a database with transactions, the COMMIT WORK and ROLLBACK WORK operations end a transaction and release all row and table locks. In addition, these statements close all cursors except those DECLAREd WITH HOLD. Unlike other cursors, you can OPEN a cursor WITH HOLD outside a transaction, and you must explicitly CLOSE the cursor.

Using SQL

3-23

SELECT Cursors

The following example outlines a typical program structure that uses a cursor WITH HOLD.
LET sel1 = "SELECT order_date FROM orders WHERE customer_num = ? FOR UPDATE" PREPARE st1 from sel1 DECLARE c_master CURSOR WITH HOLD FOR SELECT customer_num FROM customer WHERE city = "Redwood City" DECLARE c_detail CURSOR FOR st1 OPEN c_master WHILE TRUE FETCH c_master INTO p_custnum IF status = NOTFOUND THEN EXIT WHILE END IF BEGIN WORK OPEN c_detail USING p_custnum WHILE true FETCH c_detail INTO p_orddate IF status = NOTFOUND THEN EXIT WHILE END IF UPDATE orders SET order_date = "02/02/90" WHERE CURRENT OF c_detail END WHILE COMMIT WORK END WHILE CLOSE c_master

In this program, the cursor WITH HOLD provides the following advantages:

You can open the c_master cursor outside a transaction. The BEGIN WORK
statement appears after you OPEN the c_master cursor and perform a FETCH.

The COMMIT WORK at the end of each iteration of the rst WHILE loop
does not close the c_master cursor. The cursor remains open to FETCH the next master row after the COMMIT WORK has closed the c_detail cursor and released all locks. The updated rows are now available to other users on the system. If you do not use a cursor WITH HOLD, you must place the BEGIN WORK and COMMIT WORK statements completely outside the rst WHILE loop. You would open both the c_master and c_detail cursors, FETCH all master rows, and FETCH and UPDATE all detail rows within the single transaction. This approach has the following drawback: it holds all locks for the duration of the entire loop. If your program updates a large number of rows, you can

3-24

Using SQL

INSERT Cursors

approach the limits that your operating system places on the number of rows that can be locked at one time. In addition, the locked rows are unavailable to other users on the system.

Cursors WITH HOLD and Locks

In a non-MODE ANSI database with transactions, you must open any cursor DECLAREd FOR UPDATE (but not WITH HOLD) inside a transaction. (In a MODE ANSI database, all statements are automatically within a transaction.) Thus, any UPDATE or DELETE actions that are based on a cursor that is not DECLAREd as WITH HOLD occur within a transaction. You can always roll back the actions if necessary. In a database that is not MODE ANSI, you cannot roll back an UPDATE or DELETE operation performed with a cursor WITH HOLD outside of a transaction, because an SQL operation that takes place outside a transaction is treated as a singleton transaction. Any locks acquired during a singleton transaction are released as soon as the operation ends. Outside a transaction, no locks are retained from statement to statement. In short, the cursor WITH HOLD is designed to provide a natural way of doing a read-only, forward scan over a table, independent of transaction boundaries. Note the risks of using a cursor WITH HOLD outside of a transaction, namely that rows accessed by the cursor are no longer locked. Note: See the INFORMIX-OnLine Programmers Manual for a discussion of cursors WITH HOLD and locks on the INFORMIX-OnLine database engine.

Cursors WITH HOLD in a MODE ANSI Database

The cursor WITH HOLD is an Informix extension to ANSI standard syntax. You can use a cursor WITH HOLD with a database created as MODE ANSI. However, the use of the WITH HOLD keywords cause a warning message when the DBANSIWARN environment variable is set, or when the program is compiled with the -ansi ag.

INSERT Cursors
You can associate a cursor with an INSERT statement as well as a SELECT statement. The INSERT cursor permits data to be more efciently inserted into a database by buffering the data in memory and writing to the disk only

Using SQL

3-25

INSERT Cursors

when the buffer is full. The following statements allow you to declare and manipulate an INSERT cursor. (For complete information about the syntax of each statement, see Chapter 7 of the INFORMIX-4GL Reference Manual).
DECLARE

associates a cursor with an INSERT statement. (The INSERT statement cannot contain an embedded SELECT statement.) You cannot DECLARE a SCROLL INSERT cursor. sets up an insert buffer for an INSERT cursor. stores a row in the INSERT buffer for later insertion into the database. When you ll the buffer (by executing a series of PUT statements), INFORMIX-4GL automatically inserts the rows into the appropriate table as a block. forces INFORMIX-4GL to insert the buffered rows into the database without closing the INSERT cursor. You can force the insertion using the FLUSH statement, but you cannot delay insertion by not using the FLUSH statement. ushes the insert buffer and closes the INSERT cursor.

OPEN PUT

FLUSH

CLOSE

For databases with transactions, you must issue the OPEN, PUT, FLUSH, and CLOSE statements within a transaction. For example, you can use these cursor management statements to insert customers into the customer table, block by block. See the following example:
DECLARE ins_curs CURSOR FOR INSERT INTO customer VALUES (p_customer.*) OPEN ins_curs LET answer = "y" WHILE answer = "y" INPUT BY NAME p_customer.fname THRU p_customer.phone LET p_customer.customer_num = 0 PUT ins_curs PROMPT "Do you want to enter ", "another customer (y/n) ? " FOR answer END WHILE CLOSE ins_curs 3-26 Using SQL

INSERT Cursors

This example includes the following statements:

The DECLARE statement associates a cursor called ins_curs with an

INSERT statement that inserts a row into the customer table.

The OPEN statement sets up the insert buffer for the INSERT cursor. The WHILE loop includes statements that insert information entered
on a screen form into the customer table, block by block. Specically, the INPUT statement allows the user to enter customer information on a screen form and stores the information in the p_customer record. The PUT statement stores the current values in the p_customer record in the insert buffer. If the insert buffer becomes full as the result of a PUT statement, the rows are automatically inserted into the customer table as a block.

The CLOSE statement inserts any rows that remain in the insert buffer into
the customer table and closes the INSERT cursor. When you use an INSERT cursor, you should CLOSE the cursor to insert any buffered rows into the database before allowing your program to end. The user can lose data if the cursor is not closed properly. For example, if the user presses the Interrupt key during input in the following program, INFORMIX-4GL closes the INSERT cursor before leaving the program. (Any remaining rows in the insert buffer are inserted into the database before the program stops.)
DEFER INTERRUPT . . . DECLARE ins_curs CURSOR FOR INSERT INTO customer VALUES (p_customer.*) OPEN ins_curs LET answer = "y" WHILE answer = "y" INPUT BY NAME p_customer.fname THRU p_customer.phone ON KEY (INTERRUPT) CLOSE ins_curs EXIT PROGRAM END INPUT LET p_customer.customer_num = 0 PUT ins_curs PROMPT "Do you want to enter another customer (y/n) ? FOR answer END WHILE CLOSE ins_curs . . .

"

You can determine whether INFORMIX-4GL successfully executes a PUT, FLUSH, or CLOSE statement by examining the values of the status and SQLCA.SQLERRD[3] variables. (See the section SQLCA Record, later in this

Using SQL

3-27

Dynamic Management

chapter, for more information on these variables.) If INFORMIX-4GL simply puts a row in the insert buffer, it assigns the following values to these global variables:
status = 0 SQLCA. SQLERRD [3] = 0

If INFORMIX-4GL successfully inserts a block of rows into the database as a result of a PUT, FLUSH, or CLOSE statement, it assigns the following values:
status = 0 SQLCA. SQLERRD [3] = the number of rows inserted

If, as a result of a PUT, FLUSH, or CLOSE statement, INFORMIX-4GL is unsuccessful in its attempt to insert an entire block of rows into the database, it assigns the following values:
status = a negative number corresponding to the error message SQLCA. SQLERRD [3] = the number of rows successfully inserted

Dynamic Management
The preceding discussion assumes that you know what the SQL statements are when you write your 4GL programs. That is the case for most applications where you are performing predetermined activities on your database. In some advanced applications, however, you will not know the statement at compile time:

Interactive programs, where the user supplies input at run time from the
keyboard

Programs intended to work with different databases whose structure can

vary In situations like these, you must work with dynamically dened statements. There are four dynamic management statements:
PREPARE

takes a character string, interprets it as an SQL statement, and assigns it to a statement identier. Subsequent dynamic management statements refer to the SQL statement through the statement identier. runs the previously PREPAREd statement associated with the statement identier. Use EXECUTE for all PREPAREd statements except the following statements: SELECT statements

EXECUTE

3-28

Using SQL

Preparing Statements

INSERT statements that use an insert cursor

DECLARE FREE

has options that DECLARE a cursor for a PREPAREd SELECT or INSERT statement. releases the database engine resources that are required by a PREPAREd statement.

Preparing Statements
You can use the PREPARE statement with either a character string or a character variable that evaluates to an SQL statement. The form of the PREPARE statement that you choose depends on the type of input (if any) required by the statement. You can use either form of the PREPARE statement if the statement requires no input or input for values. If the statement requires input for SQL identiers such as column names, you must use the PREPARE statement with a character variable. In general, you can improve the performance of your programs by PREPARing statements that you plan to execute many times. Specically, you might want to PREPARE a statement that requires different input each time it is executed. Note: You can PREPARE any SQL statements except these:
CLOSE DECLARE EXECUTE FETCH LOAD OPEN PREPARE SELECT (with INTO variable clause) UNLOAD

See the section SQL Statement Summary earlier in this chapter for more information about SQL statements. Chapter 2 describes the INFORMIX-4GL statements which you cannot PREPARE. Note: When you issue a DECLARE statement that includes the INSERT or SELECT keywords, you declare a cursor that can perform an associated PUT or FETCH statement, even though you do not explicitly PREPARE the statement. For example,
DECLARE m_curs CURSOR FOR INSERT INTO state VALUES (code, sname)

is a cursor declaration that species an INSERT statement. When you OPEN this cursor, INFORMIX-4GL automatically PREPAREs the INSERT statement. Implicitly PREPAREd statements become an issue only if you exceed the engine resources allocated for such statements. If this happens, you can use the FREE statement to release the resources. The FREE statement is described later in this chapter.

Using SQL

3-29

Preparing Statements

Statements That Require No Input

If a statement requires no input, you can PREPARE it from either a character string or character variable. For example, the following statement
PREPARE s1 FROM "SELECT * FROM customer"

produces the same result as

DEFINE sel_stmt CHAR(25) LET sel_stmt = "SELECT * FROM customer" PREPARE s1 FROM sel_stmt

Statements That Require Input for Values

Similarly, you can use either form of PREPARE when a PREPAREd statement requires input for one or more values.

Preparing a Character String

If you use PREPARE with a character string, you must use a question mark (?) instead of a program variable in the character string as a placeholder for a value. Specically, the question mark can represent a value or expression in a character string, but not an SQL identier (such as a column name or table name). Usually, you use a question mark to represent a value in the following clauses:

The WHERE clause of a SELECT, UPDATE, or DELETE statement:

PREPARE sel1 FROM "SELECT * FROM customer WHERE lname MATCHES ?"

The VALUES clause of an INSERT statement:

PREPARE ins1 FROM "INSERT INTO manufact VALUES (?, ?)"

The SET clause of an UPDATE statement:

PREPARE upd1 FROM "UPDATE customer SET zipcode = ? WHERE CURRENT OF q_curs"

When you PREPARE a statement from a character string, you do not need to supply values for the question marks until you execute the PREPAREd statement. (See the section Executing PREPAREd Statements later in this chapter for more information.)

3-30

Using SQL

Preparing Statements

Preparing a Character Variable

Alternatively, you can PREPARE a statement that requires input for values from a character variable.

First, you use a LET statement to concatenate the variable(s) containing

the input to one or more strings that represent the rest of the statement.

Second, you PREPARE the character variable that contains the resulting
SQL statement.

The following example shows how to use this approach to PREPARE a statement that selects rows from the customer table based on a customer number that the user supplies:
DEFINE cust_num INTEGER, sel_stmt CHAR(100) PROMPT "Enter a customer number: " FOR cust_num LET sel_stmt = "SELECT * FROM customer WHERE customer_num = ", cust_num USING "###" PREPARE sel1 FROM sel_stmt

When INFORMIX-4GL encounters the LET statement in this example, it concatenates a character string containing part of the SELECT statement to the variable cust_num, which contains a customer number that the user supplies. INFORMIX-4GL then assigns the resulting string to the large character variable sel_stmt and PREPAREs it. When you use this approach, you must supply input values when you assign the SQL statement to the character variable that you will later PREPARE. Note: If you use the LET statement to concatenate strings to variables that contain CHAR or DATE values, or DATETIME or INTERVAL constants, make sure that quotes appear around those values in the resulting character string. To embed a quote in a character string, you must enter a backslash (\) followed by a double quote ("). For example, the LET statement
LET sel_stmt = "SELECT * FROM customer WHERE lname MATCHES \"", last_name CLIPPED, "\"" PREPARE s1 FROM sel_stmt

produces the following character string if the current value of last_name is Baxter:
SELECT * FROM customer WHERE lname MATCHES "Baxter"

Using SQL

3-31

Preparing Statements

In contrast, the statements like the following do not require quotation marks around placeholders for values:
DECLARE q_curs CURSOR FOR SELECT * FROM customer WHERE lname MATCHES last_name PREPARE s1 FROM "SELECT * FROM customer WHERE lname MATCHES ?"

Statements That Require Input for SQL Identiers

You must use PREPARE with a character variable to PREPARE a statement that requires data for an SQL identier (such as a column name, table name, username, view name, or synonym). The approach that you use is identical to that described in the previous section.

First, you concatenate the variable(s) representing the SQL identier(s) to

one or more character strings that contain the rest of the statement.

Second, you assign the resulting string to a large character variable and
PREPARE it.

The following example shows how to use this approach to PREPARE a statement that grants the CONNECT privilege to a specied user:
DEFINE p_user CHAR(12), grant_stmt CHAR(50) PROMPT "Enter the name of user ", "to receive CONNECT privilege: " FOR p_user LET grant_stmt = "GRANT CONNECT TO ", p_user CLIPPED PREPARE s1 FROM grant_stmt

When INFORMIX-4GL encounters the LET statement in this example, it concatenates a character string containing part of the GRANT statement to the character variable p_user, which contains a username. INFORMIX-4GL then assigns the resulting string to grant_stmt and PREPAREs it.

3-32

Using SQL

Executing PREPAREd Statements

Executing PREPAREd Statements

The method for executing a PREPAREd statement depends on the kind of statement that you want to run. The EXECUTE statement runs any PREPAREd statements except those that follow:

SELECT statements INSERT statements that require a cursor

The DECLARE statement has a special form designed to work with PREPAREd SELECT and INSERT statements.

The EXECUTE Statement

If you have PREPAREd a non-SELECT statement from a character variable or from a character string that does not contain question marks, you can run it with a simple EXECUTE statement, as shown in the following examples:
PREPARE s1 FROM "DELETE FROM customer WHERE customer_num = 115" EXECUTE s1 LET del_stmt = "DELETE FROM customer WHERE customer_num = 115" PREPARE s1 FROM del_stmt EXECUTE s1

If you PREPAREd a non-SELECT statement from a character string that does contain question marks, you must use the EXECUTE statement with a USING clause. This clause consists of the USING keyword followed by one or more program variables representing the values that replace the question marks in the PREPAREd character string.

Using SQL

3-33

Executing PREPAREd Statements

The EXECUTE statement in the following example executes a DELETE statement using a customer number that the user supplies:
PREPARE s1 FROM "DELETE FROM customer WHERE customer_num = ?" PROMPT "Do you want to delete a customer (y/n) : FOR answer WHILE answer = "y" PROMPT "Enter a customer number : " FOR cust_num EXECUTE s1 USING cust_num IF status = 0 THEN DISPLAY "Row deleted." END IF IF status = 100 THEN DISPLAY "No row found for that customer number" ELSE CALL mess("Unable to delete the customer row.") END IF PROMPT "Do you want to delete another customer (y/n): " FOR answer END WHILE "

When INFORMIX-4GL executes the PREPAREd DELETE statement in this example, it substitutes the current value of cust_num for the question mark in the character string.

3-34

Using SQL

Executing PREPAREd Statements

Running PREPAREd SELECT Statements

If you PREPAREd a SELECT statement from a character variable or from a character string that does not contain question marks, you can use a DECLARE statement with either FOREACH or OPEN, FETCH, and CLOSE. Two examples follow:
LET sel_stmt = "SELECT * FROM customer WHERE lname MATCHES \"", last_name CLIPPED, "\"" PREPARE sel1 FROM sel_stmt DECLARE q_curs CURSOR FOR sel1 FOREACH q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* . . . END FOREACH PREPARE sel1 FROM "SELECT * FROM customer" DECLARE q_curs CURSOR FOR sel1 FOREACH q_curs INTO p_customer.* DISPLAY BY NAME p_customer.* . . . END FOREACH

If you PREPAREd a SELECT statement from a character string that does contain one or more question marks, you must use the DECLARE statement with an OPEN statement that includes a USING clause. As described

Using SQL

3-35

Executing PREPAREd Statements

previously, this clause consists of the USING keyword followed by one or more program variables representing the values that replace the question marks in the character string. An example follows:
PREPARE sel1 FROM "SELECT * FROM customer WHERE zipcode MATCHES ?" DECLARE q_curs CURSOR FOR sel1 PROMPT "Enter a zipcode: " FOR zip OPEN q_curs USING zip WHILE TRUE FETCH q_curs INTO p_customer.* IF status = NOTFOUND THEN EXIT WHILE END IF DISPLAY BY NAME p_customer.* . . . END WHILE CLOSE q_curs

When INFORMIX-4GL opens the cursor for the PREPAREd SELECT statement in this example, it substitutes the current value of zip for the question mark in the character string. A Note on Preparing and Executing SELECT Statements for Update: A previous section entitled Deleting or Updating the Current Row describes how to use the DECLARE FOR UPDATE statement and a subsequent DELETE or UPDATE statement to delete or update the current row. If you want to use DECLARE FOR UPDATE with a PREPAREd SELECT statement,

3-36

Using SQL

Executing PREPAREd Statements

make sure that the FOR UPDATE clause appears as part of the PREPAREd character string or character variable and not as part of the DECLARE statement. An example follows:
PREPARE s1 FROM "SELECT * FROM customer FOR UPDATE" DECLARE q_curs CURSOR FOR s1 FOREACH q_curs INTO p_customer.* . . . DELETE FROM customer WHERE CURRENT OF q_curs END FOREACH

Running PREPAREd INSERT Statements

If you have PREPAREd an INSERT statement, you can run it by using the EXECUTE statement or the PUT statement. A previous section, The EXECUTE Statement, describes how to use the EXECUTE statement if you want INFORMIX-4GL to insert one row into the database at a time. This section explains how to DECLARE a cursor and use the PUT statement to insert rows into the database through an insert buffer. If you PREPARE an INSERT statement from a character variable or from a character string that does not contain question marks, you can use the DECLARE, OPEN, FLUSH and/or CLOSE statements with a simple PUT statement, as follows:
PREPARE s1 FROM "INSERT INTO manufact VALUES ("WLS", "Willis") DECLARE icurs CURSOR FOR s1 OPEN icurs PUT icurs . . . CLOSE icurs

If you PREPARE an INSERT statement from a character string that does contain one or more question marks, you must use the DECLARE, OPEN, FLUSH, and/or CLOSE statements with a PUT statement that includes a FROM

Using SQL

3-37

Preparing Multiple SQL Statements

clause. This clause consists of the FROM keyword, followed by one or more program variables representing the values that replace the question marks in the character string. An example follows:
PREPARE s1 FROM
"INSERT INTO customer (customer_num, company) VALUES (0, ?)"

DECLARE ins_curs CURSOR FOR s1 OPEN ins_curs LET answer = "y" WHILE answer = "y" Prompt "Enter a customer: " FOR p_customer.company PUT ins_curs FROM p_customer.company PROMPT "Do you want to enter another customer (y/n) ? FOR answer END WHILE CLOSE ins_curs "

When INFORMIX-4GL executes the PUT statement in this example, it substitutes the current value of p_customer.company for the question mark in the PREPAREd INSERT statement and stores the row in the insert buffer for later insertion into the database.

Preparing Multiple SQL Statements

INFORMIX-4GL supports PREPAREd objects that combine more than one data manipulation statement. To use this dynamic management feature involves the same procedures as for simple PREPAREd statements, but with character strings that concatenate several SQL statements that you can successively execute to perform some task. (A multiple-statement PREPARE cannot, however, reference an object like a table or synonym that is created by another SQL statement that you specify in the same PREPARE statement.)

3-38

Using SQL

The FREE Statement

The following example updates the stores database by replacing the existing manufacturer codes with new codes. Since the manu_code columns are potential join columns that link three of the tables, the task of replacing the old codes with the new must be performed in three tables.
DATABASE stores MAIN DEFINE code_change RECORD new_code LIKE manufact.manu_code, old_code LIKE manufact.manu_code END RECORD, sqlmulti CHAR(250) PROMPT "Enter new manufacturer code: " FOR code_change.new_code PROMPT "Enter old manufacturer code: " FOR code_change.old_code LET sqlmulti =
"UPDATE manufact SET manu_code = ? WHERE manu_code = ?;", "UPDATE stock SET manu_code = ? WHERE manu_code = ?;", "UPDATE items SET manu_code = ? WHERE manu_code = ?"

PREPARE exmulti FROM sqlmulti EXECUTE exmulti USING code_change.*, code_change.*, code_change.* END MAIN

This program prompts the user for both the new and the old three-letter code. It then updates all corresponding rows in three tables (manufact, stock, and items) as a single action.

The FREE Statement

You can create a PREPAREd statement explicitly in a PREPARE statement, which assigns an INFORMIX-4GL identier to the statement that you specify in the FROM clause. You can also create a PREPAREd statement implicitly, by associating a cursor with a DECLARE statement that includes the SELECT or INSERT keywords. When you specify that cursor in an OPEN statement, INFORMIX-4GL automatically PREPAREs the associated INSERT or SELECT statement. Both explicitly and implicitly PREPAREd statements require database engine resources. You can ignore this cost in typical programs, but there is a limit to the number of PREPAREd objects that the 4GL application can create.

Using SQL

3-39

Data Access

The FREE statement is useful in this situation where you are at the engines limit on the number of PREPAREd objects. In effect, it unPREPAREs a statement, releasing the resources that had been allocated to that statement, so that you can use them to PREPARE something else. The FREE statement supports two formats:
FREE statement-name FREE cursor-name

Always use the rst form if you explicitly PREPAREd the statement. The second form is for implicitly PREPAREd statements to which you assigned no statement-name. If you assigned a statement-name with PREPARE, freeing an associated cursor does not release the PREPAREd statement. After a successful FREE statement, you cannot use statement-name with a cursor or with EXECUTE unless you PREPARE it again. If you FREE a cursor, you cannot use it again until you OPEN it.

Data Access
A user has access to the database, a table, and to specic columns within a table only when the DBA or the owner of the table specically grants these privileges. You can temporarily limit access to a table by executing the LOCK TABLE statement. (Under transactions, the affected rows are locked until the transaction is complete. Explicit table/record locking is generally not required.) The following SQL statements affect data access:
GRANT REVOKE LOCK TABLE

grants database access privileges to specic users or to the public. removes database access privileges from specic users or from the public. limits access to the table to the current user only, or allows other users only to read the table. Use the LOCK TABLE statement only when making major changes to a table in a multiuser environment and when simultaneous interaction with the table by another user would interfere. LOCK TABLE decreases the accessibility of the database, since it prevents other users from accessing the table. If the database has transactions and is not MODE ANSI, you must issue a BEGIN WORK statement before you can issue the LOCK TABLE statement. restores access to a previously LOCKed table.

UNLOCK TABLE 3-40 Using SQL

User Status and Privileges

See the next section, User Status and Privileges, for further information. Use of the LOCK TABLE and UNLOCK TABLE statements is described in the section Locking later in this chapter. Chapter 7 identies the various keywords that can specify user privileges in the GRANT and REVOKE statements.

User Status and Privileges

When you create a database, you are automatically the DBA of that database and are the only one who has access to the database. Another user does not have access to a database until you grant the CONNECT privilege to that person. Another user cannot create or drop tables and indexes unless granted the RESOURCE privilege. Only the DBA (you, initially) can grant these privileges. You can also grant the DBA privilege to another user. The DBA privilege extends all the powers of the Database Administrator to the grantee, including the ability to alter the system tables; to drop, start, and roll forward the database; and to grant CONNECT, RESOURCE, and DBA privileges to others. If you have the RESOURCE privilege, you have the CONNECT privilege by default. With the DBA privilege, you have both the RESOURCE and CONNECT privileges. You can only revoke the privilege of a DBA grantee; you cannot revoke your own DBA privilege. If you, as the creator of a database, grant DBA privileges to another user, that user can revoke the DBA privilege from you, the database creator. This last property permits the transfer of authority from the maker of the database application to the person who has responsibility for maintaining the database.
INFORMIX-4GL allows the CONNECT and RESOURCE privileges to be granted TO PUBLIC, in addition to specically named users.

In addition to these database-level privileges, the owner of the table can grant a collection of table-level privileges . These privileges permit the grantee access to specic columns to execute SELECT or UPDATE statements, or give the grantee authority to insert new rows, delete old rows, create indexes, and alter the structure of the table. In a non-MODE ANSI database, the default is to grant all table-level privileges (except ALTER) to all users (PUBLIC). In a MODE ANSI database, no default table-level privileges are granted. You must explicitly grant these privileges. However, if you use START DATABASE to convert your database to MODE ANSI, the existing privileges remain in effect unless you specically revoke them.

Using SQL

3-41

Data Integrity

Several of the SQL statements (ALTER TABLE, ALTER INDEX, DROP INDEX, DROP TABLE, DROP VIEW, GRANT, RENAME COLUMN, RENAME TABLE, REVOKE) can be executed only by the DBA or by the owner of the specied table or index. (You can give others the privilege of executing the ALTER TABLE, GRANT, and REVOKE statements, with certain restrictions.) The owner of a table is the username of the person who executed the CREATE TABLE statement. The owner of an index is the one who executed the CREATE INDEX statement. Execution occurs when the compiled INFORMIX-4GL program containing the CREATE statements is run, not when the INFORMIX-4GL program is compiled.

Data Integrity
INFORMIX-4GL has features to protect the integrity of your data. These

features include recovery procedures through transaction logs and audit trails, and concurrency control through record locking and table locking.

Transactions
INFORMIX-4GL supports data integrity by implementing the idea of transactions. A transaction is a series of database operations (SQL statements) that

you want to be completed entirely or not at all. Examples of transactions are abundant in bookkeeping, where several operations on several different accounts must be made as a unit or the books will be out of balance. You can use the following statements to control transactions in INFORMIX-4GL programs: marks the start of a transaction (if the database is not BEGIN MODE ANSI). WORK marks the end of a transaction by authorizing all database COMMIT changes since the transaction began. WORK marks the end of a transaction by revoking all database ROLLBACK changes since the transaction began. WORK initiates a new transaction log le and (optionally) START converts a database to MODE ANSI. DATABASE ROLLFORWARD uses a transaction log le to restore a database from backup. DATABASE The BEGIN WORK, COMMIT WORK, ROLLBACK WORK, and ROLLFORWARD DATABASE statements are only available when the database has a transaction log. You can use the WITH LOG IN clause of the CREATE DATABASE or START DATABASE statements to create a transaction log le that records all modi3-42 Using SQL

Transactions

cations to the database. If you also specify the MODE ANSI option, transactions are implicit, and you are always within a transaction. You terminate the transaction when you issue a COMMIT WORK or ROLLBACK WORK statement. In terms of transactions, there are three kinds of 4GL databases:

A database that has no transaction log is described as a database without

transactions.

A database created or started with a transaction log and as MODE ANSI

is described as a database with implicit transactions. (A synonymous term is a MODE ANSI database.)

A database created or started with a transaction log, but not as MODE

ANSI, is a database with explicit transactions. (You use the BEGIN WORK statement to begin a transaction.)

Databases Without Transactions

A database without transactions may require considerable recovery effort if it becomes corrupted through failure of a data manipulation statement, particularly if the error occurs within a series of closely related database operations that form a single unit of work. For example, under transactions, you can UPDATE several rows as a single unit of work. If the UPDATE fails after changing some of the rows but not all, you can ROLLBACK the transaction to the original state where no rows are modied. Without transactions, you must take explicit action to restore the updated rows. (The Audit Trails section later in this chapter describes a recovery procedure for databases without transactions.)

Databases with Implicit Transactions

If you want a database to have implicit transactions, you must create or start the database as MODE ANSI and specify a transaction log le. All SQL statements are automatically part of a transaction. Note: You do not need to use the BEGIN WORK statement with a MODE ANSI database, since the statement is implied.

Using SQL

3-43

Transactions

Databases with Explicit Transactions

If your database supports explicit transactions, you must issue the BEGIN WORK statement before you perform a series of operations that you want to consider a unit. This statement causes all subsequently altered rows of the database tables to be locked against modication by others (although others can view them). If you do not execute the BEGIN WORK statement, INFORMIX-4GL treats each data manipulation statement that changes the database as a singleton transaction. Each statement, if it executes successfully, is committed, and the database is permanently altered. If the statement fails, there is an automatic rollback to the status before the statement. You must execute cursor manipulation statements inside a transaction if your database supports explicit transactions. That is, rst execute the BEGIN WORK statement before opening a cursor. All open cursors that are not WITH HOLD are closed by the COMMIT WORK and ROLLBACK WORK statements.

Using Transactions
The number of rows that can be locked at one time by all users is limited. The actual limit depends on your operating system. Try to restrict the denition of a transaction to a few statements that involve only a few rows. If you expect that the number of rows to be entered during the transaction will be large, LOCK the tables involved until the transaction is completed. Regardless of whether a transaction is explicit or implicit, you can terminate the transaction with a COMMIT WORK statement when you are satised that the series of operations has produced the desired results. If you are not satised with the results, you can terminate the transaction with a ROLLBACK WORK statement. With the exceptions stated in the next paragraph, this statement restores the database to the state that existed immediately before the transaction began. Both the COMMIT WORK and the ROLLBACK WORK statements release all row and table locks, making the data accessible for modication by others. On INFORMIX-SE, you cannot roll back GRANT or REVOKE statements, nor any of the data denition statements. These statements alter the number or names of tables, or change the number, names, data types, or indexes of columns. If they were executed successfully, they are committed, and the ROLLBACK WORK statement cannot undo them. If your database supports explicit transactions, you should not use these statements within a transaction.

3-44

Using SQL

Transaction Log File Maintenance

Transaction Log File Maintenance

The transaction log le can become quite large and, periodically, the DBA will want to archive it on tape and initiate another log le. At the same time, the DBA should also create a backup of your database. In general, every log le must have a corresponding archive copy of the database. After backing up the log le and the database, the DBA must specify an empty log le. To reuse the same log le, the DBA should create an empty log le with the same name as the old one. The DBA can do this with the following command:
cat /dev/null > logfile

To change the name of the log le, the DBA must execute the START DATABASE statement just before making a backup of the database. The START DATABASE statement locks the database in EXCLUSIVE MODE while it is operating so that no further changes can be made. If START DATABASE fails, no database is open. If the database is without transactions and you want to use transactions, the DBA must execute the START DATABASE command just before making a copy of the database. If there is a backup copy of the database and a transaction log le that begins with the operations executed immediately after the backup was made, the DBA can bring the backup database up to date with the ROLLFORWARD DATABASE statement. This statement recovers the database through the last terminated transaction. The DBA must load the backup database les and execute the ROLLFORWARD DATABASE statement. After rolling the database forward, the DBA is the only one who has access to the database, since it is left in an exclusive mode. This state allows the DBA to check the database for errors before making it generally available. Logging does not occur during this checking phase. The DBA must close the database when it has been restored correctly.

Audit Trails
An audit trail is a le that contains a history of all additions, deletions, updates, and manipulations to a database table. An audit trail serves a purpose similar to that of a transaction log: each is used to maintain a record of modications to a database, and each can be used to update backup copies of a database. Three audit trail statements are available to protect the integrity of a table:
CREATE AUDIT DROP AUDIT

creates an audit trail for a table. removes the audit trail on a table.
Using SQL 3-45

Audit Trails

RECOVER TABLE restores a table using the audit trail.

Creating an Audit Trail

Use the CREATE AUDIT statement to create an audit trail le and to begin writing the audit trail. The format is
CREATE AUDIT FOR table-name IN "pathname"

Here table-name is the name of the table for which you want to create an audit trail le and pathname is the full pathname of the audit trail le. The audit trail le should be on a physical device other than the one that holds the data so that a system failure affecting the device that holds the data does not also damage the audit trail. If your computer system has more than one hard disk, the audit trails should be written to a disk not containing the data. To use the audit trail, make a backup copy of the table after you have executed a CREATE AUDIT statement, but before you have made any changes to the table. Once you have started the audit trail and have made a backup, you are ready to work with the table. You can drop and create an audit trail le whenever you want. Drop and create the audit trail les just before you make a complete backup of the device containing the data le. If a system failure should occur, you can use the audit trail to back up the table from the time of the last backup to the time when the failure occurred.

Recovering a Table
In the event of a system failure, you can use the RECOVER TABLE statement to restore a database table by using a backup copy of the table and an audit trail le. You must rst restore a backup copy of the table. The backup copy must be in the original state that it was in when the audit trail was started. If it is not in the original state, the recovery fails. The format of the recovery statement is
RECOVER TABLE table-name

where table-name is the name of the table you want to recover. Once you recover the table, use the DROP AUDIT statement to remove the contents of the audit trail le. Then run the CREATE AUDIT statement to start a new audit trail le. Finally, make a new backup copy of the table.

3-46

Using SQL

Comparison of Transactions and Audit Trails

Comparison of Transactions and Audit Trails

Transactions provide data integrity in two ways. First, they guarantee that SQL statements are either successfully completed or completely canceled. If, for example, you update several rows of one or more tables within a transaction, the entire update is guaranteed either to succeed by updating all rows, or to fail without changing any rows. Second, you can use the transaction log to recover an entire database. Audit trails are associated with individual tables. They do not guarantee that modications to several rows of a table either succeed entirely or fail without any effect. You can use an audit trail le only to recover the table for which it is created. You should consider using audit trails in place of a transaction log only when you have one or a few critical tables and you do not need the additional facilities provided by transactions. If you need to maintain the integrity of the database as a whole, or need the guarantee that SQL statements are executed as a unit either entirely or not at all, you must use transactions.

Locking
INFORMIX-4GL uses locking to prevent different users from executing conicting operations on the same data. Without locking, for example, two users could be allowed to update the same row at the same time. In this situation, the computer memory contains two different versions of the rows (the one updated by user A and the one updated by user B). Without some method of concurrency control, the user whose row is the last one actually written to the le wins and overwrites changes by the other user.

The following SQL statements control locking: limits access to the table to the current user only or allows other LOCK users only to read the table. Use the LOCK TABLE statement TABLE only when making major changes to a table in a multi-user environment, and when simultaneous interaction with the table by another user would interfere. LOCK TABLE decreases the accessibility of the database since it prevents other users from accessing the table. If the database has transactions but is not MODE ANSI, you must issue a BEGIN WORK statement before you can issue the LOCK TABLE statement. restores access to a previously locked table. UNLOCK
TABLE

Using SQL

3-47

Row-Level Locking

SET LOCK MODE

alters the locking strategy, either to fail when a row is already locked, or to wait for the lock to be released before proceeding. (This statement is supported only on systems with UNIX System V locking, or with shared memory.)

In addition, in the rare instance in which you need to limit access to the entire database to a single user, you can open the database in EXCLUSIVE mode. INFORMIX-4GL provides two levels of locking:

Row-level or record-level locking Table-level or le-level locking

INFORMIX-4GL performs row-level locking implicitly. The locking strategy

can differ slightly, depending on whether or not the database uses transaction management. Data denition statements, such as ALTER TABLE, CREATE INDEX, and so on, use implied table-level locking. You can explicitly specify table-level locking. The following sections describe each level of locking and the methods for its use. Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.

Row-Level Locking
Ordinarily, INFORMIX-4GL locks a row when you execute an UPDATE statement, or when you execute a FETCH statement and the cursor is DECLAREd with a FOR UPDATE clause. If the UPDATE statement affects only one row, INFORMIX-4GL releases the lock immediately after performing the update. Locking the row prevents two programs from attempting to update the same row at the same time. One program receives the lock and can proceed with the update. The other program either fails in its attempt or waits for that program to release the lock. (See the section Wait for Locked Row later in this chapter.) If the UPDATE statement affects more than one row, INFORMIX-4GL uses the same row-locking strategy. As soon as a row is UPDATEd, the lock is released and the next row is locked and UPDATEd. When the UPDATE nishes, all rows are unlocked. If you want more control over the update of multiple rows, you can DECLARE a cursor FOR UPDATE. The WHERE clause of the SELECT statement species the rows you want to update. After you OPEN the cursor and FETCH a row, that row remains locked until you either CLOSE the cursor or FETCH the next row.

3-48

Using SQL

Table-Level Locking

Row-Level Locking in Transactions

If your database uses transaction management, rows that you INSERT, UPDATE or DELETE within a transaction remain locked until the end of the transaction. The end of a transaction is either a COMMIT WORK, where all modications are made to the database, or a ROLLBACK WORK, where none of the modications are made.
INFORMIX-4GL locks a row when it is selected for update. For example, if you DECLARE a cursor FOR UPDATE, the FETCH statement locks the row. If the row is updated, it remains locked until the end of the transaction. If the row is not updated, the lock is released upon the next FETCH.

Table-Level Locking
Use table-level locking to lock an entire table and prevent others from altering or seeing rows in that table. You may want to use this form of locking, for example, during batch operations that affect every row in a table. If the operations must be completed as a single transaction, it may be more efcient to lock the entire table before beginning the transaction. Normally, under transactions, INFORMIX-4GL locks each row manipulated by an UPDATE, DELETE, or INSERT statement. If you lock the entire table, however, INFORMIX-4GL does not use row-level locking, because it is not necessary. As a result, you are not likely to reach the limit that your operating system can place on the number of rows that can be locked at any one time. INFORMIX-4GL performs table-level locking automatically as part of the following statements: ALTER TABLE, DROP TABLE, CREATE INDEX, ALTER INDEX, and DROP INDEX. The LOCK TABLE statement has two extensions:

If you lock the table IN SHARE MODE, other users are able to SELECT data
from the table, but they are not able to INSERT, DELETE, or UPDATE rows in the table.

If you lock the table IN EXCLUSIVE MODE, other users are not able to
access the table at all until you execute an UNLOCK TABLE statement. Because locking an entire table prevents others from adding or altering data in the table, use this feature sparingly. Lock the entire table only when rowlevel locking (as described in the previous section) is not sufcient.

Using SQL

3-49

Wait for Locked Row

Wait for Locked Row

If another user locks a row in a table at the row level and you attempt to alter or delete that row (or examine it with SELECT statement FOR UPDATE), INFORMIX-4GL returns an error, stating that the row is locked. If you prefer that INFORMIX-4GL wait on any locked row until the competing process unlocks it, you can execute the SET LOCK MODE TO WAIT statement. From then on, your request waits until INFORMIX-4GL unlocks the requested row, and you do not receive an error code. If another user locks a table IN EXCLUSIVE MODE and you attempt to alter, delete, or even read a row in the table, INFORMIX-4GL returns an error code. The wait-for-lock feature applies only on systems that support kernel locking. Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.

Indexing Strategy
There are two major purposes for creating an index on columns of a database table: to speed sorting of rows and to optimize the performance of queries. When your application writes reports involving complex queries through a large database, signicant time savings can result from judicious indexing. The drawback to having an index is that indexes slow down the process of inserting new data into the database. When you update a table, its indexes can also be modied. This is not a problem when you are adding information interactively, a row at a time, but can become serious when it is necessary to insert a large number of rows from one table into another. The solution to this potential conict between needs is to take a dynamic approach to indexing. One of the advantages of an Informix relational database is that you do not have to decide issues like which columns to index at the time that you create your tables. You should write your applications to create indexes when you need them and to drop them when they get in the way. It takes time to create an index on a table already containing data, and you should create only those indexes that optimize the queries you make. For example, by judicious scheduling, you can create your indexes in anticipation of batch report writing during the night and drop them the next morning before there are huge data-entry needs.

3-50

Using SQL

Indexing Strategy

The following are hints for strategic indexing. Although the last two items refer to a single query, they apply when you anticipate making a number of queries with the same qualities.

Do not create indexes for small tables with fewer than 200 rows. Speed
that you gain from using an index does not overcome the time required to open and search the index le on small tables.

Do not create indexes on a column that has only a few possible values.
Such columns are those that contain data like sex, marital status, yes/no responses, or zip codes in a small city. Because data like this produces skewed indexes, indexing can cause the optimizing strategy of INFORMIX-4GL to fail and queries to take longer than if the columns were not indexed. If you have a frequent need to have data sorted on columns with a small range of possible values, create a temporary table of the sorted data. Another approach is to redesign the database with separate tables for each alternative value.

If the WHERE clause of a SELECT statement imposes a condition on a single column, put an index on that column. If conditions are placed on several columns, make a composite index on all the affected columns. For the SELECT statement
SELECT * FROM items WHERE order_num > 1015

put an index on order_num. For the statement

SELECT * FROM items WHERE order_num = 1015 AND total_price = 1000.00

create a composite index on both order_num and total_price.

If the WHERE clause of a SELECT statement has a join condition between

a single column in one table and a single column in another table, create an index on the column in the table with the larger number of rows. If several columns of one table have join conditions with several columns in another table, create a composite index on the affected columns of the table with the larger number of rows. For the SELECT statement
SELECT * FROM items, stock WHERE items.stock_num = stock.stock_num

place an index on stock_num in the items table, since it has many more rows than the stock table. You should execute the UPDATE STATISTICS

Using SQL

3-51

Query Optimizer

statement before the SELECT statement so that INFORMIX-4GL knows the current size of the tables. For the statement
SELECT * FROM items, stock WHERE items.stock_num = stock.stock_num AND items.manu_code = stock.manu_code

put a composite index on stock_num and manu_code in the items table.

Query Optimizer
It is not always easy to know how indexes are used during a query, but you can determine this by issuing the SET EXPLAIN statement. When you set this statement to ON, a le called sqexplain.out is created in the current directory. A description of the decisions made by the query optimizer, a feature of the database engine to improve performance, is written into this le for each subsequent query. The recorded information includes the order of table access, how lters are applied, and what (if any) indexes are used in processing the query. For example, if your queries seem to be taking longer than necessary, you may choose to change your indexing strategy. However, in a complex query, it may be difcult to predict the actual order of actions taken by the optimizer, thus making it difcult to determine what (if any) indexes should be added or dropped. The SET EXPLAIN statement provides you with information to determine exactly how the database is being accessed and to help you assess whether changing indexes may improve the decisions of the optimizer.

Auto-Indexing
If you execute a SELECT statement that includes a join between two tables and there are no indexes on the joined columns, INFORMIX-4GL creates a temporary index on the table with the larger number of rows before performing the join. The index disappears when the query nishes. This enhancement is transparent to the user, except for a dramatic improvement in the speed of unindexed joins.

Clustered Indexes
Since UNIX systems extract information from the disk in blocks, rows physically on the same block and already in the order of an index are retrieved more quickly. Ordinarily, no relationship need exist between the physical

3-52

Using SQL

NULL Values

order of the data in the .dat le and the order in an index. You can, at least temporarily, make the physical order in the table the same as the order in an index through clustering.
INFORMIX-4GL orders, or clusters, the physical data in a table when you create a new index by executing a variant of the CREATE INDEX statement or when you execute the new ALTER INDEX statement for an existing index. Since users who have access to the table can add additional rows or update the information in existing rows, a table that you cluster according to an index does not stay that way. Over time, you can expect the benet of an earlier clustering to disappear and you may want to cluster the table again using an ALTER INDEX TO CLUSTER statement.

Since a table can have only one physical order, you can have only one clustered index on a table at any given time. You can change the physical order to reect a different index by executing two ALTER INDEX statements: 1. Execute an ALTER INDEX TO NOT CLUSTER statement to release the cluster attribute from the rst index. 2. Execute an ALTER INDEX TO CLUSTER statement to attach the cluster attribute to the second index. You cannot execute the ALTER INDEX or CREATE INDEX statements on a view.

NULL Values
The basic purpose of introducing NULL values in a database is to indicate when no value has been assigned to a particular column in a particular row of a table. Your reasons for not having assigned a value could include not knowing the correct value, or that no value yet exists. The NULL can also indicate that no value is appropriate for a given column because of the values that were entered into other columns. As an example, consider entering data for a bank customer who is requesting a loan. If the customer, Mr. Farthing, is not employed, the employer column in the client table will have no entry for this customer. This CHAR column will have the value NULL. The hire_date column is meaningless if Mr. Farthing is not employed. There is no appropriate date to enter; the value is NULL.

Using SQL

3-53

Default Values

Default Values
In INFORMIX-4GL, the default value for a column is NULL. INFORMIX-4GL makes a distinction for number values between zero and NULL, and for character values between blanks and NULL. You do not need to know how INFORMIX-4GL implements the value NULL to make use of it. By denition, type SERIAL columns can never contain the NULL value. Columns of type SERIAL always contain integers greater than or equal to one. You can insist that a column of any type not have NULL values by using the NOT NULL clause in the CREATE TABLE statement. INFORMIX-4GL will prevent a NULL from being entered into any column that is declared NOT NULL. You cannot, however, use a NOT NULL clause in an ALTER TABLE statement when you add a new column. The reason is that INFORMIX-4GL enters a NULL value into that column for all rows that already exist. A column for which you create a unique index can have, at most, one NULL value. Note for Users with an SQL Version 1 Database: When no value is provided for a column entry in a row of a table in an SQL Version 1 database, INFORMIX-4GL enters a blank for type CHAR columns, zeros for number columns, and a very large negative value for type DATE columns. Since zero could well be an acceptable value for a number column (for example, the value for a type MONEY column), there is no way to distinguish an unknown value from zero. To incorporate an existing SQL Version 1 database into INFORMIX-4GL programs, you must execute the dbupdate utility described in Appendix E. (The discussion of the dbupdate utility describes how you can avoid using NULL values.)

The NULL in Expressions

If any value that participates in an arithmetic expression is NULL, the value of the entire expression is NULL. For example, consider the following query:
SELECT order_num, ship_charge/ship_weight FROM orders WHERE order_num = 1023

If ship_weight is NULL because the order with number 1023 is new and the shipping charge has not yet been determined, the value returned for ship_charge/ship_weight will also be NULL.

3-54

Using SQL

The NULL in Boolean Expressions

The situation is different when you use one of the aggregate functions. (See Chapter 7 for a description of the aggregate functions.) COUNT(*) counts all rows, even if the value of every column in the row is NULL. COUNT (DISTINCT column-name), AVG, SUM, MAX, and MIN ignore rows with NULL values for the column in their argument and return the appropriate value based on the rest of the rows. If, however, a column contains only NULL values, then COUNT (DISTINCT column-name) returns zero, and the other four aggregate functions return NULL for that column.

The NULL in Boolean Expressions

To incorporate NULL values into Boolean expressions, it is necessary to enlarge the number of truth values from simply TRUE and FALSE to include UNKNOWN. If one of the expressions of a Boolean expression is NULL, the truth value of the Boolean expression is UNKNOWN. For example, the Boolean expression,
ship_charge/ship_weight < 5.0

has the truth value UNKNOWN for the order in the previous example. If you combine Boolean expressions using the operators AND, OR, and NOT, the following tables give the resulting truth value (where T corresponds to TRUE, F to FALSE, and ? to UNKNOWN). AND T F ?
Figure 3-1

T T F ?

F F F F

? ? F ?

OR T F ?

T T T T

F T F ?

? T ? ?

NOT T F ? F T ?

Combining Boolean Expressions

The NULL in WHERE Clauses

If the Boolean expression in a WHERE clause evaluates to UNKNOWN for a particular row, INFORMIX-4GL treats the search condition as not satised and does not select or modify that row. Consider this clause
WHERE ship_charge/ship_weight < 5 AND order_num = 1023

Using SQL

3-55

The NULL in ORDER BY Clauses

The row where order_num = 1023 is the row where ship_weight is NULL. Since ship_weight is NULL, ship_charge/ship_weight is also NULL, and the truth value of ship_charge/ship_weight < 5 is UNKNOWN. Since order_num = 1023 is TRUE, the preceding AND truth table states that the truth value of the entire search condition is UNKNOWN. Consequently, that row will not be chosen. If the search condition had used an OR in place of the AND, the search condition would be TRUE. You can select (or reject) rows containing NULL values with a new type of search condition:
column IS [ NOT ] NULL

You must use the keyword IS. It is not permitted to write the condition as follows:
column = NULL column != NULL (Incorrect) (Incorrect)

If you perform a join between two tables using the WHERE clause,
WHERE column1 = column2 INFORMIX-4GL will not select the rows where either column1 or column2 is NULL. In particular, no row will be returned if both column1 and column2 are NULL. This is merely a special case of the more general rule that Boolean expressions containing NULL values have an UNKNOWN truth value.

Similarly, if a subquery returns a single NULL value, the search condition evaluates to UNKNOWN.

The NULL in ORDER BY Clauses

For the purpose of sorting rows using the ORDER BY clause, the NULL value is treated as being less than a non-NULL value. When the ordering is ascending ( ASC ), the NULL values come rst; when the ordering is descending ( DESC ), the NULL values come last.

The NULL in GROUP BY Clauses

When you refer to a column in a GROUP BY clause, INFORMIX-4GL treats all rows containing a NULL value in the column as a single group. NULL values are considered identical when evaluated within a GROUP BY clause.

3-56

Using SQL

The NULL Keyword in INSERT and UPDATE Statements

The NULL Keyword in INSERT and UPDATE Statements

When you execute the INSERT statement, INFORMIX-4GL will insert the NULL value into all columns for which you do not provide a value, or for all columns not listed explicitly. Since the value-list of the INSERT statement must be the same length as the column-list, you can use the keyword NULL to indicate that a column in column-list should be assigned a NULL value.
INSERT INTO orders (order_num, order_date, customer_num) VALUES (0, NULL, 123)

All other columns in the orders table will be lled with NULL values. Similarly, you can use the NULL keyword to modify a column value when using the UPDATE statement. For a customer whose previous address required two address lines, but now requires only one, you would use the following entry:
UPDATE customer SET address1 = "123 New Street", address2 = NULL, city = "Palo Alto", zipcode = "94303" WHERE customer_num = 134

Views
Views are constructs on a database that allow you to do the following tasks:

Provide different users with different windows (called views) on the

data in the database. A single view can involve columns from different tables, or can show values that are functions of the values from the columns. A view has a name and looks to a user as if it were a table. The user can query a view, for example, using the same syntax as though the view were a table in the database.

Limit access to sensitive data by allowing users to see only aggregate

information. With the GRANT and REVOKE statements, you can prevent a user from seeing any salary data in a personnel table. With a view, you can allow the user to see average salaries in various groups, but still protect the individual salary data.

Permit users to update, insert, and to delete data in the database as

though the data were organized as it appears in a view. You can also examine through a view the changes made in a real table of the database.

Using SQL

3-57

Creating and Deleting Views

Views are therefore dynamic windows into the database and are not static snapshots. They differ in this respect from a temporary table created by the INTO TEMP clause of a SELECT statement or the CREATE TEMP TABLE statement. Such temporary tables show you only the state of the database when the temporary table was created. Although views appear to be tables in the database, they differ in several important ways. You cannot create an index on a view. Under certain conditions, you cannot update or modify the data perceived through a view. An obvious case occurs when the column seen in a view is really an expression generated from actual database tables. Generally speaking, there is no way to determine the appropriate change in the underlying columns involved in such an expression if you want to change the value of the column. The next sections describe how to create and delete views, how to query the database through views, how to modify the database through a view, and how to set up privileges for a view.

Creating and Deleting Views

You must use the CREATE VIEW statement to create a view. (See Chapter 7 for complete information about the CREATE VIEW statement.) A view is determined by a SELECT statement that returns the table that denes the view. You cannot use the UNION operator in the denition of a view. (See Chapter 7 for the denition of the UNION operator.) The SELECT statement is stored in the sysviews system catalog. When you subsequently refer to a view in another statement, INFORMIX-4GL performs the dening SELECT statement in executing the new statement. You can use the same column names as in the underlying table for the view or you can assign new names. When a column in a view is the evaluation of an expression or is not unique (because, for example, you have included all the columns of a join, including the columns that dene the join), you must supply new names. These column names are stored in syscolumns with the column names of regular tables. You can delete a view by executing the DROP VIEW statement. When you drop a view, you also drop all views that were dened in terms of that view.

Querying Through Views

You can make queries involving views exactly as though they were tables in the database. If possible, 4GL rst combines the view-dening SELECT statement with the query to create a new SELECT statement and then executes the
3-58 Using SQL

Modifying Through Views

new statement. Otherwise, it creates the view as a temporary table and applies the query to the table. 4GL can detect errors during either of these phases.

Modifying Through Views

In addition to querying through views, you can use the INSERT, UPDATE, and DELETE statements with views. INFORMIX-4GL combines the view-dening SELECT statement with the view-referring statement and then executes it. The following restrictions apply when modifying tables through a view:

You cannot modify the database through a view if the view denition
involves joins, the GROUP BY clause, the DISTINCT keyword, or an aggregate function. If any of these features appears in the view denition, the creator of the view cannot execute INSERT, DELETE, or UPDATE statements on the view. You can dene a view, however, using a subquery that refers to another table. This approach can often circumvent the restriction on joins. (See the section Data Constraints Using Views, later in this chapter.)

A view column can be UPDATEd only if it is derived directly from a database table and not as a result of an expression. Expression-derived columns are called virtual columns. You cannot INSERT rows through a view that contains virtual columns, although you can DELETE a row that contains a virtual column.

You cannot execute the ALTER TABLE, CREATE INDEX, ALTER INDEX, or
UPDATE STATISTICS statements on a view. You do, however, receive the benet of existing indexes on the underlying tables.

You can use an INSERT statement on a view that shows only a portion of an underlying table. When you do so, the unmentioned columns of the underlying table will receive NULL values. If one of the unmentioned columns does not permit NULL values, INFORMIX-4GL will not permit you to INSERT to the view. If you drop a column from a table underlying a view and you have dened the view in terms of that column, INFORMIX-4GL issues an error if you subsequently refer to the view (other than with the DROP VIEW statement). Unless you create the view with a WITH CHECK OPTION clause, it is possible to INSERT or UPDATE data through a view that does not satisfy the limitations on the view. A row inserted or updated in this manner is no longer accessible through the view. For example, a view could be created that allows the user access only to customers from Palo Alto. If, when using the view, the user creates a new row with a customer from Menlo Park, the user cannot
Using SQL 3-59

Privileges with Views

select the row through the view. If the city column on an existing row is updated to Menlo Park, the row disappears from the view. The WITH CHECK OPTION clause in the CREATE VIEW statement causes INFORMIX-4GL to reject an UPDATE or INSERT that violates the restrictions of the view. You must be careful when you UPDATE a table through a view that can contain duplicate rows. Duplicate rows can occur in a view even if the underlying table has unique rows. If a view is dened on the items table and contains only the columns order_num and total_price, the view contains duplicate rows if two items from the same order have the same total price. If you put the cursor on one of the rows where total_price = $1234.56 and update the total_price to $1250.00 through the view, you have no way of knowing which item you have increased.

Privileges with Views

When you create a view, you receive the same privileges that you had on the underlying tables. If you have these privileges with the GRANT OPTION, you can grant privileges on your view to other users. (See Chapter 7.) If the view is built on more than one table, you can have only the SELECT privilege, since multi-table views do not permit you to INSERT, DELETE, or UPDATE. You must have the SELECT privilege on all of the columns from which a multi-table view is derived to have the SELECT privilege on the entire view. If, as a result of these restrictions, you have no privileges on a view, the CREATE VIEW statement returns an error code.

Data Constraints Using Views

The purpose of data constraints is to ensure that all data entered into the database satises pre-assigned limitations. Through a form in INFORMIX-4GL, data entry can be controlled with the INCLUDE attribute that lists values and ranges of values permitted for a column. The values entered into the syscolval table in the include column serve a similar purpose. (See Chapter 4.) In both of these cases, however, the list of allowed values is static and is dependent only on the designated column. It is often desirable to dene allowed value ranges dynamically, based on the values in other columns or even in other tables. The existence of views and, specically, the WITH CHECK OPTION clause permits the DBA to control the entry of data into the database. This is most easily demonstrated with an example taken from the stores database.

3-60

Using SQL

Outer Joins

Suppose you want to ensure that no item

Has a value of more than $20,000 Is for stock that does not exist
The rst step is to create the following view:
CREATE VIEW safe_items AS SELECT * FROM items WHERE total_price < 20000 AND EXISTS (SELECT stock_num, manu_code FROM stock WHERE stock.stock_num = items.stock_num AND stock.manu_code = items.manu_code) WITH CHECK OPTION

If you do all data entry and data modication through the safe_items view, 4GL will reject all data that does not meet the requirements of the WHERE clause. Because of the dynamic nature of views, the view will only contain rows corresponding to current stock items if you change the stock table by adding rows corresponding to new stock items or deleting old ones. By extending the WHERE clause, this example can be expanded to cover very general data-constraint needs.

Outer Joins
An outer join between two tables treats the two tables unsymmetrically. One of the tables is dominant (often referred to as preserved), and the other table is subservient. If the subservient table has no rows satisfying the join condition, the outer join attaches a row of NULL values to the row of the dominant table before projecting the desired columns. To illustrate, let a be a column from tab1 and b a column in tab2. Further, let the values in the two tables be as shown in the following display:
tab1.a 2 3 5 tab2.b 4 2 6 5

Using SQL

3-61

Table Access by ROWID

INFORMIX-4GL syntax requires that the subservient table in an outer join be preceded by the keyword OUTER in the FROM clause. The following SELECT

statement contains an outer join between tab1 (the dominant table) and tab2 (the subservient table):
SELECT a, b FROM tab1, OUTER tab2 WHERE a = b

The resulting table has the following three rows:

a 2 3 5 b 2 5

Every value for a is present, and only those values for b that correspond to a value in a are present. When there is no value in column b that satises the join condition, a NULL value (shown here as -) is substituted. A WHERE clause is required in the case of outer joins and must set a condition between the two tables. See Appendix G for more information about outer joins.

Table Access by ROWID

You can use the keyword ROWID in INFORMIX-4GL statements to refer to the internal record number associated with a row in a database table. The ROWID can be thought of as a hidden column in every table. When you refer to table.*, the implied list of columns does not include ROWID. On the other hand, you can use the syntax
SELECT ROWID , * FROM table

to get the ROWID value for each row. You can also determine the ROWID of the last row that INFORMIX-4GL dealt with by examining the SQLCA record. See the next section for how to do this. You can also use ROWID in WHERE clauses to select rows based on their internal record number. This feature is useful when there is no other unique column in a table. If a row is deleted from the table, its ROWID can be assigned to a new row. You should not attribute chronological or other signicance to the sequential values of ROWID.

3-62

Using SQL

SQLCA Record

SQLCA Record
Proper database management requires that all logical sequences of statements that modify the database continue successfully to completion. If, for example, you UPDATE a customer account to show a reduction of $100 in the payable balance and the next step, to UPDATE the cash balance, fails for some reason, your books will be out of balance. It is prudent to check that every SQL statement executes as you anticipated.
INFORMIX-4GL provides two ways to do this: the global variable status that indicates errors both from form-related statements and SQL statements; and a global record SQLCA that allows you to test the success of SQL statements. The status variable provides the primary information, and SQLCA provides additional information. INFORMIX-4GL returns a result code into the SQLCA record after executing every SQL statement except DECLARE. This record is shown here: DEFINE SQLCA SQLCODE SQLERRM SQLERRP SQLERRD SQLAWARN END RECORD SQLCODE RECORD INTEGER, CHAR(71), CHAR(8), ARRAY [6] CHAR (8)

OF

INTEGER ,

indicates the result of executing an SQL statement. It is set to zero for a successful execution of most statements and to NOTFOUND ( = 100 ) for a successfully executed query that returns zero rows or for a FETCH that seeks beyond the end of an active set. is negative for an unsuccessful execution.
INFORMIX-4GL sets the global variable status equal to SQLCODE after each SQL statement. See Error Messages after the

SQLCODE

appendixes for the error codes.

SQLERRM SQLERRP SQLERRD

is not used at this time. is not used at this time. an array of six variables of type INTEGER
SQLERRD[1] SQLERRD[2] SQLERRD[3] SQLERRD[4]

is not used at this time. is the SERIAL value returned or ISAM error code. is the number of rows processed. is the estimated CPU cost for query.
Using SQL 3-63

SQLCA Record

SQLERRD[5] SQLERRD[6]

is the offset of error into the SQL statement. is the ROWID of last row.

SQLAWARN is a character string of length eight whose individual characters

signal various warning conditions (as opposed to errors) following the execution of an SQL statement. The characters are blank if no problems were detected.
SQLAWARN[1] is set to W if one or more of the other warning characters has been set to W. If SQLAWARN[1]

is blank, you do not have to check the remaining warning characters.

SQLAWARN[2] is set to W if one or more data items was truncated to t into a CHAR program variable, or if a DATABASE statement selected a database

with transactions.
SQLAWARN[3] is set to W if an aggregate function ( SUM, AVG, MAX, or MIN ) encountered a NULL value in its evaluation, or if a DATABASE statement selected a MODE ANSI database. SQLAWARN[4] is set to W if a DATABASE statement selected an INFORMIX-OnLine database, or when the number of items in the select-list of a SELECT

clause is not the same as the number of program variables in the INTO clause. The number of values returned by INFORMIX-4GL is the smaller of these two numbers.
SQLAWARN[5] is set to W if oat-to-decimal conversion is

used.
SQLAWARN[6] is set to W when your program executes an INFORMIX-4GL extension to ANSI standard syntax, and the DBANSIWARN environment

variable is set.
SQLAWARN[7] is not used at present. SQLAWARN[8] is not used at present.

3-64

Using SQL

TODAY, CURRENT, and USER Functions

TODAY, CURRENT, and USER Functions

INFORMIX-4GL provides functions to allow you to include the date, the date and time of day, and the login name of the current user in an SQL statement. TODAY returns the system date. CURRENT returns the system date and time. USER returns a string containing the login account name of the current user.

You can use these functions in SQL statements wherever you can use a constant of a similar data type. TODAY returns a DATE, CURRENT a DATETIME, and USER a CHAR value. You can also use CURRENT and TODAY (but not USER) in 4GL statements. For example, if you wish to retrieve the rows that you have inserted into a table, you must dene a CHAR column to contain the USER name. When you insert new rows into the table, use the USER function as follows:
INSERT INTO table VALUES ( . . . , USER , . . . )

With a SELECT statement, you can retrieve the rows that you entered:
SELECT * FROM table WHERE user_col = USER

(See the sectionCursor Management, earlier in this chapter, for a discussion on using the SELECT statement to return multiple rows.) Use the TODAY function in the same way. You can insert the system date into a table with the following statement:
INSERT INTO table VALUES ( . . . , TODAY , . . . )

The next statement retrieves all rows with the current date from table:
SELECT * FROM table WHERE date_col = TODAY

You can use CURRENT to insert the system date and time:
INSERT INTO table VALUES ( . . . , CURRENT , . . . )

The next query selects rows whose DATETIME value is within a range from the beginning of 1989 to the current instant.
SELECT * FROM table WHERE dt_col BETWEEN "1989-1-1 00:00:00" AND CURRENT

See the section Built-in Functions in Chapter 2 for more information about the TODAY and CURRENT functions.

Using SQL

3-65

TODAY, CURRENT, and USER Functions

3-66

Using SQL

Chapter

Form Building and Compiling

Chapter Overview 3 Structure of a Form Specication File 4 DATABASE Section 7 SCREEN Section 9 Textual Information 11 Display Fields 11 Graphics Characters in Forms 13 TABLES Section 15 ATTRIBUTES Section 17 Fields Linked to Database Columns Form-Only Fields 19 Multiple-Line Fields 21 Multiple-Column Fields 22 Attributes Syntax 23 AUTONEXT 24 COLOR 26 COMMENTS 28 DEFAULT 30 DISPLAY LIKE 32 DOWNSHIFT 33 FORMAT 34 INCLUDE 36 NOENTRY 38 PICTURE 39 REQUIRED 41 REVERSE 43 UPSHIFT 44 VALIDATE LIKE 46 VERIFY 47

4
18

WORDWRAP 48 INSTRUCTIONS Section 52 Field Delimiters 53 Screen Records 55 Screen Arrays 56 Default Screen Attributes 57 The upscol Tables in a MODE ANSI Database

60

Creating and Compiling a Form 61 Through the Programmers Environment 62 Through the Operating System 63 Using PERFORM Forms in INFORMIX-4GL 64

4-2

Form Building and Compiling

Chapter Overview
A screen form is a terminal screen display that can support input or output tasks within a 4GL application program. You can use screen forms in conjunction with screen interaction and data manipulation statements of INFORMIX-4GL to enter, retrieve, modify, or delete data. Before you can use a customized screen form in your INFORMIX-4GL program, you must create a form specication le and use FORM4GL to compile this le. The form specication le is an ASCII le that contains the screen format and the instructions to INFORMIX-4GL about how to display the data. The rst and longest section of this chapter, Structure of a Form Specication File, describes the function and syntax of each of the required and optional components of a 4GL form specication le. Another part of this chapter, Default Screen Attributes, describes the syscolval and syscolatt tables into which you can insert default attributes, formats, and values for screen elds of 4GL applications. The section Creating and Compiling a Form describes how to use FORM4GL to compile form les for use in INFORMIX-4GL programs. The last section, Using PERFORM Forms in INFORMIX-4GL describes what happens when an INFORMIX-4GL program uses screen forms designed for PERFORM, the screen transaction program of INFORMIX-SQL. Note: The FORM4GL syntax for forms that you design to work with INFORMIX-4GL is different in several signicant ways from the syntax of PERFORM. You can use PERFORM forms with INFORMIX-4GL, but you must recompile them using FORM4GL. In addition, not all of the PERFORM features are operative.

Form Building and Compiling

4-3

Structure of a Form Specication File

Structure of a Form Specication File

An INFORMIX-4GL form specication le consists of three required sections (DATABASE, SCREEN, and ATTRIBUTES) and can also include two optional sections (TABLES and INSTRUCTIONS). If present, these sections must appear in the following order:

DATABASE Section: Each form specication le must begin with a DATABASE section identifying the database (if any) on which you want to

base the form.

SCREEN Section: The SCREEN section appears next, showing the exact layout of the form as you want it to appear on the screen. You must specify the position of the screen elds for data entry and display, and any additional text or graphic characters. TABLES Section: A TABLES section must follow the SCREEN section if you dene any eld with the name of a column in a database table. The TABLES section identies all the tables whose columns are associated with screen elds in the ATTRIBUTES or INSTRUCTIONS sections, and denes aliases for any table names or synonyms that require an owner qualier. ATTRIBUTES Section: The ATTRIBUTES section describes each eld on

the form and assigns names to elds. The eld specications can include, for example, appearance, acceptable input values, on-screen comments, and default values.

INSTRUCTIONS Section: The INSTRUCTIONS section is optional. It can

specify non-default eld delimiters and can dene screen records and screen arrays. Each section must begin with the keyword for which it is named. After you create a form specication le, you use the FORM4GL utility to compile it. Your INFORMIX-4GL application can then use program variables to transfer information between a database and the elds of the screen form, as is illustrated by the examples that appear in Chapters 7, 11, 12, and 13 of the INFORMIX-4GL User Guide.

4-4

Form Building and Compiling

Structure of a Form Specication File

A FORM4GL form specication le has this structure:

DATABASE { database-name | FORMONLY } [ WITHOUT NULL INPUT ] SCREEN [ SIZE lines [ BY cols ] ] { [text] [ [eld-tag] ] [graphics-char] ... } [ END ] [ TABLES [ tab-alias = [ owner. ] table ] ... [ END ] ] ATTRIBUTES

eld-tag = { table.column

| FORMONLY. eld-name [ TYPE [ data-type [ NOT NULL ] | LIKE table.column ] ] } [ , attribute-list ] [ = . . . ] [ ; ] [ = . . . ] ;

... [ END ] [ INSTRUCTIONS [ DELIMITERS "ab" ] [ SCREEN RECORD record-name [ [ n ] ] ( { table.* | table.column1 THRU table.column2 | table.column } [ , . . . ] ) ...] [ END ] ]

This summary includes three exceptions to the usual syntax notation of this manual. The following are literal characters to be entered in your le, rather than conventional symbols to mark optional terms:

the set of braces ( { } ) in the SCREEN section the inner brackets ( [ ] ) around eld-tag in the SCREEN section the inner brackets ( [ ] ) around n in the INSTRUCTIONS section
The next ve sections of this chapter identify the keywords and terms listed previously, and describe their syntax in detail.

Form Building and Compiling

4-5

Structure of a Form Specication File

Example
Figure 4-1 illustrates the overall structure of form specication les:
DATABASE stores SCREEN { -------------------------------------------------------------------------CUSTOMER INFORMATION: Customer Number: [c1 ] Telephone: [c10 ] ... SHIPPING INFORMATION: Customer P.O.: [o20 Ship Date: [o21 } TABLES customer orders items manufact ATTRIBUTES c1 = customer.customer_num = orders.customer_num; ... c10 = customer.phone, PICTURE = "###-###-####x#####"; ... o20 = orders.po_num; o21 = orders.ship_date; o22 = orders.paid_date; INSTRUCTIONS SCREEN RECORD sc_order[5] (orders.order_date THRU orders.paid_date)

] ] Date Paid: [o22 ]

Figure 4-1

Sections of a Form Specication File

In this example, the screen form will display columns from several tables in the stores database. The le is for a default physical screen size (24 lines of 80 characters) and includes all ve of the required and optional sections that are described in the pages that follow. This example is incomplete, since it omits portions of the SCREEN and ATTRIBUTES sections that describe some of the screen elds. The ellipsis notation ( . . . ) in those sections is a typographic device to simplify this illustration.

4-6

Form Building and Compiling

DATABASE Section

DATABASE Section
Overview
The DATABASE section of a form specication le identies the database (if any) with which the form is designed to work. You must include this section, even if your screen form does not refer to the tables of any database. The DATABASE section has this structure.

Syntax
DATABASE { database-name | FORMONLY } [WITHOUT NULL INPUT]

Explanation
DATABASE

is a required keyword to mark the beginning of the DATABASE section of a form specication le. is the name of a database that contains columns used to dene display elds of the form. are keywords to indicate that database-name does not support NULL values. is a keyword to indicate that the screen form is not associated with any database.

database-name
WITHOUT NULL INPUT FORMONLY

Notes
1. You should use the WITHOUT NULL INPUT option only if you have elected to create and work with a database that does not have NULL values. (See the description of dbupdate in Appendix E for the other required steps.) For elds that have no other defaults, this option causes INFORMIX-4GL to display zeros as default values for number and INTERVAL elds, and blanks for character elds. The default DATE value is 12/31/1899, and the default for DATETIME is 1899-12-31 23:59:59.99999. 2. It is possible to create a form that is not related to a database. To do so, specify FORMONLY after the DATABASE keyword, and omit the TABLES section of the form specication le. Use the table name formonly in the ATTRIBUTES section in naming elds that are not linked to specic columns of a database.
Form Building and Compiling 4-7

DATABASE Section

Examples
The following DATABASE section species that any columns referenced in the TABLES section are in the stores demonstration database:
database stores

The next example of a DATABASE section species that the screen form is not associated with any database:
database formonly

4-8

Form Building and Compiling

SCREEN Section

SCREEN Section
Overview
The SCREEN section of the form specication le species the vertical and horizontal dimensions of the physical screen, and the position of display elds and other information that will appear on the screen form. This section is required. It has the following syntax:

Syntax
SCREEN [ SIZE lines [ BY cols ] ] { screen-layout } [ END ]

Explanation
SCREEN SIZE

is a required keyword to mark the beginning of the SCREEN section. is an optional keyword to specify the vertical and horizontal dimensions of the terminal screen. is an integer that species the total number of lines of characters (measured vertically) that the terminal screen can display. The default is 24 lines. is an optional keyword to specify how many characters (measured horizontally) a line can display. is an integer that species the width of the screen. The default is the maximum number of characters in any line of the screen-layout. is the group of display elds and optional text and graphics characters that dene a screen form. The braces ( { } ) are required symbols to indicate the beginning and end of the screen-layout, and do not represent a choice among required options. is an optional keyword to mark the end of the SCREEN section.

lines

BY

cols

{ screen-layout }

END

Form Building and Compiling

4-9

SCREEN Section

Notes
1. If you omit the SIZE keyword, lines defaults to 24, and cols defaults to the maximum number of characters in any line of your screen-layout. If you specify a default form at the Programmers Environment, as described near the end of this chapter, these SIZE defaults appear explicitly in the le. 2. Your form4gl command line can override either or both of the lines or cols dimensions of the SCREEN section by specifying: form4gl -l lines -c cols form-name Here lines and cols are dened as above, and form-name is the lename (without the .per extension) of a form specication le. 3. Specify lines as the total screen height. Four lines are reserved for the system, so no more than ( lines - 4 ) can display data. 4. If ( lines - 4 ) is less than the number of lines in the screen-layout, FORM4GL splits your form into a new page after every (lines - 4) lines. INFORMIX-4GL does not support multiple-page forms, so any lines beyond the rst page will overlay the last line of the rst page if your screen-layout is too large for your screen. (Create several form specication les if you need to display more data than can t on one form.) 5. If the SIZE clause or command line specify dimensions too small for the screen-layout, FORM4GL issues a compile-time warning, but still produces the compiled form that your le specied. 6. The screen-layout must be enclosed in braces ( { } ). It consists of display elds and (optionally) textual information and graphics characters. Display elds must be indicated by brackets ( [ ] ) that dene the eld length and the position within a line of the form, and by eld tag labels within the eld. 7. Do not use braces as comment indicators in the screen-layout. 8. As in the other sections of a form specication le, the keyword END is not required, but it is recognized by FORM4GL to provide compatibility with earlier Informix products.

4-10

Form Building and Compiling

SCREEN Section

Example
This gure schematically illustrates the structure of a SCREEN section. Here the SCREEN SIZE dimensions specify a physical screen that can display up to 35 lines of data, with up to 80 characters in each line. (Four of the 39 lines specied here are reserved for the system.)
SCREEN SIZE 39 BY 80 { . . .

Text, display elds, and graphic characters

. . . } [ END ]

Screen layout

Textual Information
A screen layout can specify strings of ASCII characters that appear on the screen form. These characters can label the form and its elds, or otherwise improve the display. Except for the displacements described later in Graphics Characters in Forms, position in the screen layout determines where text appears on the screen. Text cannot overlap display elds, but the PICTURE attribute (described in Attributes Syntax later in this chapter) can specify literal characters within CHAR elds.

Display Fields
You can indicate where data will be displayed on the screen by using brackets ( [ ] ) to delimit elds in the screen layout. You must label each eld with an associated eld tag to identify the eld.

Syntax
[eldtag ]

Explanation
[ ] are delimiters for a eld. The width of the eld is the number of characters that can be placed between the brackets. (The brackets are required in this context, and do not signify an optional syntax.) is the eld tag that labels the display eld.
Form Building and Compiling 4-11

eldtag

SCREEN Section

Notes
1. Each eld must have a eld tag, enclosed within brackets. 2. The eld tag is from 1 to 50 characters long. It must t within the brackets. The rst character must be a letter. The rest of the eld tag can include letters, numbers, and underscores ( _ ). 3. Field tags are labels; they are not the same as eld names. The ATTRIBUTES section links each eld tag to a eld name. 4. The same eld tag can be used at more than one position in the SCREEN section of the form specication, if you want the same information to appear in more than one screen eld, or if you dene a multiple-line eld, or a screen array. (Multiple-line elds and screen arrays are described later in this chapter.) 5. The case of a eld tag is ignored (so a1 and A1 are the same). 6. You can give single-character elds the tags a through z (so a form can include no more than 26 single-character elds.) 7. In a default form specication le, the widths of all elds are determined by the data type of the corresponding columns in the database tables. (See Creating and Compiling a Form for more information about default form specication les.) 8. If you create your own form, you normally should set the width of each display eld in the SCREEN section to be equal to the width of the program variable or column to which it corresponds. 9. Fields corresponding to number columns should be large enough to contain the largest number that you might display. If the eld is too small to display an assigned number, INFORMIX-4GL lls the eld with asterisks ( * ) to indicate the overow. 10. Fields intended to display character data can be shorter than the dened column length. INFORMIX-4GL lls a eld from the left, and truncates from the right any character string that is longer than the eld to which it is assigned. Through subscripting, you can assign portions of a character column to one or more elds. (See the ATTRIBUTES Section later in this chapter.) 11. If you edit and modify the default form specication le or create a new le, you can verify that the eld widths match the width requirements of the corresponding CHAR columns by using the -v option of FORM4GL. At the system prompt, enter: form4gl -v form-name
FORM4GL reports any discrepancies in the le form-name.err. 4-12 Form Building and Compiling

SCREEN Section

12. The INSTRUCTIONS Section later in this chapter describes an optional delimiter that can be used to separate consecutive display elds in a screen layout.

Example
The SCREEN section listed below appears in the orderform.per form specication le in the INFORMIX-4GL demonstration application. This uses default screen dimensions (24 by 80). Notice the use of textual information for eld labels, a screen title, and ornamental lines. (The INSTRUCTIONS Section later in this chapter describes how repeated eld tags are used in forms that dene screen arrays.)
SCREEN { ------------------------------------------------------------------------------ORDER FORM ------------------------------------------------------------------------------Customer Number:[f000 ] Contact Name:[f001 ][f002 ] Company Name:[f003 ] Address:[f004 ][f005 ] City:[f006 ] State:[a0] Zip Code:[f007 ] Telephone:[f008 ] ------------------------------------------------------------------------------Order No:[f009 ] Order Date:[f010 ] Purchase Order No:[f011 ] Shipping Instructions:[f012 ] ------------------------------------------------------------------------------Item No. Stock No. Code Description Quantity Price Total [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] Running Total including Tax and Shipping Charges:[f019 ] =============================================================================== } END

Graphics Characters in Forms

You can include graphics characters in the SCREEN section to place boxes and other rectangular shapes in a screen form. Use the following characters to indicate the borders of one or more boxes on the form:
Symbol

p q b d |

Purpose Use p to mark the upper-left corner. Use q to mark the upper-right corner. Use b to mark the lower-left corner. Use d to mark the lower-right corner. Use hyphens ( - ) to indicate horizontal line segments. Use vertical ( | ) bars to indicate vertical line segments. Form Building and Compiling 4-13

SCREEN Section

The meanings of these six special characters are derived from the gb or acsc specications in the termcap or terminfo les, respectively. INFORMIX-4GL substitutes the corresponding graphics characters when you display the compiled form. Once the form has the desired conguration, use the \g string to indicate when to begin graphics mode and when to end graphics mode. Insert a \g string before the rst p, q, d, b, hyphen, or vertical bar that represents a graphics character. To leave graphics mode, insert the string \g after the p, q, d, b, hyphen, or vertical bar. Do not insert a \g string into original white space of a screen layout. The backslash should displace the rst graphics character in the line, and push the remaining characters to the right. The process of indicating graphics distorts the appearance of a screen layout in the SCREEN section, compared to the corresponding display of the screen form. You can include other graphics characters in a form specication le. The meaning, however, of a character other than the p, q, d, b, hyphen, and vertical bar is terminal-dependent. To use graphics characters, the system termcap or terminfo les must include entries for the following variables: termcap: gs ge gb terminfo: smacs rmacs acsc the escape sequence for entering graphics mode. the escape sequence for leaving graphics mode. the concatenated, ordered list of ASCII equivalents for the six graphics characters used to draw the border. the escape sequence for entering graphics mode. the escape sequence for leaving graphics mode. the concatenated, ordered list of ASCII equivalents for the six graphics characters used to draw the border.

See Appendix I, Modifying termcap and terminfo, and the manual that comes with your terminal for information about making changes to your termcap or terminfo les to support these graphics characters.

4-14

Form Building and Compiling

TABLES Section

TABLES Section
Overview
The third section of the form specication le lists all the tables that you reference elsewhere in the screen form. You do not need to display in the screen form every column of every table listed, but any table or view whose columns are referenced in the form must be included. In a MODE ANSI database, a form must qualify any table name with the owner prex if the form will be run by users other than owner. If a prex is needed, you must specify a simple alias for owner.table-name in the TABLES section to reference the table in other sections of the form specication le. The structure of the TABLES section is shown below:

Syntax
TABLES [tab-alias = [ owner.] ] table . . . [ END ]

Explanation
TABLES

is a keyword to begin the TABLES section. is the table alias in the form specication le. is the username of whoever created tabname. is the identier or synonym of table in its database. is an optional keyword to end the TABLES section.

tab-alias owner table

END

Notes
1. If the DATABASE section species FORMONLY, no TABLES section is needed unless you give a eld the VALIDATE LIKE or DISPLAY LIKE attribute in the ATTRIBUTES section, or type a eld LIKE a database column. 2. Every table listed in the TABLES section must be part of the database that you specify in the DATABASE section. 3. Every database column referenced in the ATTRIBUTES section must be part of some table specied in the TABLES section.

Form Building and Compiling

4-15

TABLES Section

4. The table identier is the name listed in the tabname column of the systables catalog, or else a synonym. You do not need to specify tab-alias, unless the form will be used in a MODE ANSI database by a user who did not create table. 5. Except to assign a tab-alias in the TABLES section, a form le cannot qualify table with an owner prex. You must dene a tab-alias to reference the owner of a table or synonym. (This alias can be the same identier as table, for example stock can be the alias for tom.stock) 6. Statements in INFORMIX-4GL programs or in other sections of the form specication le can reference screen elds as column or as table. column, but they cannot specify owner. table. column. You cannot specify table. column as a eld name if you dene a different tab-alias for table. 7. INFORMIX-4GL allows you to specify up to 20 tables, but the actual limit on the number of tables and views in a form is machine-dependent. 8. The END keyword is not required.

Examples
The le orderform.per in Appendix A lists four tables:
TABLES customer orders items stock

The following TABLES section species aliases for two tables:

TABLES tab1 tab2 = = refdpt.booktab athdpt.balltab

Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.

4-16

Form Building and Compiling

ATTRIBUTES Section

ATTRIBUTES Section
Overview
The ATTRIBUTES section associates an identier and a data type with every eld in the SCREEN section. You can also describe the behavior and appearance of each eld by using attributes to describe how INFORMIX-4GL should display the eld, specify a default value, limit the values that can be entered, or set other parameters. Attributes are described later in this chapter, in the sectionAttributes Syntax.

Syntax
ATTRIBUTES eld-tag = eld-description ; ... [ END ]

Explanation
ATTRIBUTES

is a required keyword to mark the beginning of the ATTRIBUTES section. is a eld tag specied in the SCREEN section. is an optional keyword to mark the end of the ATTRIBUTES section.

eld-tag
END

eld-description species a eld name and optional attributes.

Notes
1. The ATTRIBUTES section must describe every eld-tag from the SCREEN section. (Tags with more than one eld-description are described later in Multiple-Column Fields.) 2. The order in which you list the eld tags determines the order of elds in the default screen records. (See the INSTRUCTIONS Section for more information about screen records.) 3. The equal ( = ) sign and the semicolon ( ; ) are required symbols. 4. A eld not associated with any column is called a form-only eld.

Form Building and Compiling

4-17

ATTRIBUTES Section

Fields Linked to Database Columns

You can specify two kinds of eld descriptions: those that associate a eld tag with the data type and default display attributes of a database column, and those that link eld tags to form-only elds. Unless a screen eld is form-only, its eld-description must specify the identier of some column in the database as the name of the eld. Screen elds are associated with database columns only during the compilation of the form specication le. During the compilation process, FORM4GL examines two optional tables, syscolval and syscolatt, for default values of the attributes that you have associated with any columns of the database. (See the section Default Screen Attributes later in this chapter for a discussion of these tables.) After FORM4GL extracts these default attributes and identies the data types from the system catalogs, the association between the elds and database columns is broken. INFORMIX-4GL programs must mediate between screen elds and database columns with program variables.

Syntax
eld-tag = [ table.] column [ , attr-list ] ;

Explanation
eld-tag table column is a eld tag that identies a eld in the SCREEN section. is a table name or alias from the TABLES section. is the name of a column in table or, if you omit table, in some table listed in the TABLES section. This name can also appear in 4GL statements that reference the eld. is one or more FORM4GL eld attribute specications, separated by commas.

attr-list

Notes
1. Although you must include an ATTRIBUTES section that names every eld-tag, you are not required to specify any attributes. 2. You need to specify table only if column occurs in more than one table of the TABLES section. FORM4GL issues an error during compilation if there is ambiguity. Because you can refer to eld names collectively through a screen record built upon all the elds related to a single table, your forms may be easier to work with if you specify table for each eld.

4-18

Form Building and Compiling

ATTRIBUTES Section

(The INSTRUCTIONS Section provides more information about screen records.) 3. A screen eld can display a portion of a character string by using subscripts in the column specication. Subscripts are comma-separated integers in square ( [ ] ) brackets to indicate starting and ending character positions within a string value.

Examples
The ATTRIBUTES section in the following le lists elds linked to columns in the customer table. The UPSHIFT and PICTURE attributes listed here are described later in this chapter.
DATABASE stores SCREEN { Customer Name:[f000 Address:[f002 City:[f004 Telephone:[f006 } TABLES customer

][f001 ] ][f003 ] ] State:[a0] Zip Code:[f005 ] ]

ATTRIBUTES f000 = customer.fname; f001 = customer.lname; f002 = customer.address1; f003 = customer.address2; f004 = customer.city; a0 = customer.state, UPSHIFT; f005 = customer.zipcode f006 = customer.phone, PICTURE = "###-###-#### XXXXX";

Form-Only Fields
Form-only elds are not associated with columns of any database. They can be used to enter or display the values of program variables. If the DATABASE section species FORMONLY, this is the only kind of eld description that you can specify in the ATTRIBUTES section.

Syntax
eldtag = FORMONLY. eld-name [ TYPE [ data-type [ NOT NULL ] | LIKE [ table. ] column ] ] [ , attr-list ] ;

Form Building and Compiling

4-19

ATTRIBUTES Section

Explanation
eld-tag
FORMONLY

is the eld tag used in the SCREEN section. is a keyword indicating that the eld does not correspond to a column of a table in the database. is an SQL identier for the name of the eld. is a keyword to specify an INFORMIX-4GL data type. is any one of the INFORMIX-4GL data types except SERIAL. (See the section Database Data Types in Chapter 3 for definitions of the data types.) is a keyword to associate the screen eld with the data type specication of a database column. is a table alias, name, or synonym. is the name of a column in the database. are keywords to specify that, if you reference this eld in an INFORMIX-4GL INPUT or INPUT ARRAY statement, the user must enter a value in the eld. is a list of one or more FORM4GL display eld attribute specications, separated by commas. (See the section Attributes Syntax for a list of FORM4GL attributes.)

eld-name
TYPE

data-type

LIKE

table column
NOT NULL

attr-list

Notes
1. You must specify a data-type only if you use the INCLUDE or DEFAULT attribute for this eld. Otherwise, FORM4GL assumes the eld is a CHAR type whose length is the width of the eld. INFORMIX-4GL performs the necessary data conversion for the corresponding program variable during input or display. 2. When describing data-type, do not give a length to type CHAR, DECIMAL, or MONEY elds, since the length is determined by the display width in the SCREEN section. 3. If you specify one or more FORMONLY elds, INFORMIX-4GL behaves as if they formed a database table named formonly, with the eld names as column names. 4. When the DATABASE section has the WITHOUT NULL INPUT clause, the NOT NULL keyword instructs INFORMIX-4GL to use zero (number types) or blanks (character types) as a default value for this eld in INPUT or INPUT ARRAY statements. If you do not specify any type, INFORMIX-4GL treats the eld as type CHAR.

4-20

Form Building and Compiling

ATTRIBUTES Section

Examples
The following form-only elds could be used in an order entry form to display information about items:
f020 = f021 = f022 = f023 = f024 = TYPE formonly.manu_name; formonly.description; formonly.unit_price; formonly.unit_descr; formonly.order_placed DATETIME YEAR TO HOUR NOT NULL, DEFAULT = CURRENT;

The demonstration application uses the following form-only eld to store the running total price for the order as items are entered:
f019 = formonly.t_price;

Multiple-Line Fields
If you need to enter or display long character strings from program variables, you can specify multiple-line elds that occupy several lines. To create a multiple-line eld, repeat the same eld tag in different elds of the layout in the SCREEN section, typically on successive lines. You must also specify the WORDWRAP attribute for that eld tag in the ATTRIBUTES section. During input and display, INFORMIX-4GL treats these elds as segments of a single eld. The following example shows only the SCREEN and ATTRIBUTES sections of a form specication le that species a multiple-line eld:
SCREEN SIZE 24 BY 80 { title: [title author: [author ] synopsis: [synopsis [synopsis [synopsis [synopsis [synopsis } . . . ATTRIBUTES title = booktab.title; author = booktab.author; synopsis = booktab.synopsis, WORDWRAP COMPRESS;

] ] ] ] ] ]

Since the screen eld whose tag is synopsis appears in ve physical segments in the screen layout and has the WORDWRAP attribute, it is a multiple-line eld. Its value is composed of the physical segments taken in top-to-bottom, left-to-right order. The eld should ordinarily be as long or longer than the column, so it can display all of the text. Users of your 4GL application pro-

Form Building and Compiling

4-21

ATTRIBUTES Section

gram may expect all segments to be the same size and laid out in vertical alignment, as in the example, but that is not required. Segments can be of different sizes, and distributed over the screen in any arrangement. In the description of the eld in the last line of the ATTRIBUTES section, the keyword WORDWRAP enables a multiple-line editor. If you omit it, words cannot ow from segment to segment of the eld, and users must move the cursor from eld to eld with Arrow keys or the RETURN key to edit values in the form. (See the description of the WORDWRAP attribute later in this chapter for more information about the multiline editor and about the COMPRESS keyword.)

Multiple-Column Fields
A screen form that contains information from several database tables can include screen elds that display data via program variables from two or more database columns. The database columns that you assign to the same eld must have the same eld size. Usually they also have the same data type. If they are character columns, they must have the same length. The following specication in the ATTRIBUTES section assigns two column names to a eld tag, so that the names table1. column and table2. column both reference the same eld: eld-tag = table1.column = table2.column; You can also include one or more attribute lists in eld descriptions when you assign several columns to the same eld. The placement of attributes determines when they take effect. When INFORMIX-4GL executes an INPUT, INPUT ARRAY, DISPLAY, or DISPLAY ARRAY statement, the screen elds listed (explicitly or implicitly) in the 4GL statement are called active elds. If you want an attribute to apply regardless of which eld name is active, place the attribute in an attr-list after the last eld name: eld-tag = table1.column = table2.column, attr-list; If you want different attributes to apply for each of the eld names, place a semicolon ( ; ) after the attribute list for each eld name: eld-tag = table1.column, attr-list1; = table2.column, attr-list2; Here attr-list1 is effective when table1.column is active, and attr-list2 is effective only when table2.column is active. (The FORMAT and REVERSE attributes, described later in this chapter, always take effect if you include them in the description of a multiple-column eld, regardless of their placement.)

4-22

Form Building and Compiling

ATTRIBUTES Section

Attributes Syntax
FORM4GL recognizes the following display eld attributes: AUTONEXT COLOR COMMENTS DEFAULT DISPLAY LIKE DOWNSHIFT FORMAT INCLUDE NOENTRY PICTURE REQUIRED REVERSE UPSHIFT VALIDATE LIKE VERIFY WORDWRAP [ COMPRESS ]

Syntax for assigning each of these attributes is described in the sections that follow. For simplicity and clarity, these descriptions of the attributes that you can assign to a screen eld use the following syntax format:
eld-tag = [ table. ] column, attr ;

Here eld-tag is a eld tag that was specied in the SCREEN section, column or table.column is the name of a screen eld (either linked to a database column or FORMONLY ), and attr species an attribute. This format is simplied by ignoring multiple-column elds, and by omitting terms that specify the data-type and NOT NULL keywords of a form-only eld. Here is the complete syntax of a eld description that assigns one or more attributes.

Syntax
eld-tag = { [ table. ] column | FORMONLY. eld-name [ TYPE [ data-type [ NOT NULL ] | LIKE [ table. ] column ] ] } , attr [ , attr ] [ = . . . ] [ ; ] [ = . . . ] ;

Refer to this complete syntax if you need to specify a form-only eld or a multiple-column eld. Note: INFORMIX-OnLine supports an additional attribute, PROGRAM. Refer to the INFORMIX-OnLine Programmers Manual for more information.

Form Building and Compiling

4-23

AUTONEXT

AUTONEXT
Overview
Use the AUTONEXT attribute to cause the cursor to advance automatically during input to the next eld when the current eld is full.

Syntax
eld-tag = [ table. ] column, AUTONEXT;

Explanation
eld-tag table.column
AUTONEXT

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword that tells INFORMIX-4GL to advance the cursor to the next eld when the current eld is full.

Notes
1. You specify the order of elds in each INPUT or INPUT ARRAY statement. 2. AUTONEXT is particularly useful with character elds in which the input data are of a standard length, such as numeric postal codes, or the abbreviations in the state table. It is also useful if a character eld has a length of one, since only one keystroke is required to enter the data and to move to the next eld. 3. If data entered in the eld does not meet requirements of other attributes like INCLUDE or PICTURE, the cursor does not automatically move to the next eld, but remains in the current eld. 4. If the most recent OPTIONS statement species INPUT WRAP, the next eld after the last eld is the rst eld.

4-24

Form Building and Compiling

AUTONEXT

Example
The demonstration application uses the customer form to enter all the names and addresses of the customers. The following excerpt from the ATTRIBUTES section of the customer form uses the AUTONEXT attribute:
... a0 = customer.state, DEFAULT = "CA", AUTONEXT; f007 = customer.zipcode, AUTONEXT; f008 = customer.phone; ...

When two characters are entered into the customer.state eld (thus lling the eld), the cursor moves automatically to the beginning of the next eld (the customer.zipcode eld). When ve characters are entered into the customer.zipcode eld (lling this eld), the cursor moves automatically to the beginning of the next eld (the customer.phone eld).

Form Building and Compiling

4-25

COLOR

COLOR
Overview
You can use the COLOR attribute to display eld text in color on color monitors, or to specify other video attributes for eld text.

Syntax
eld-tag = [ table. ] column, COLOR = dispmode [ . . . ] [ WHERE condition ] ;

Explanation
eld-tag table.column
COLOR =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a database column or FORMONLY). is a keyword, followed by an equal ( = ) sign. is the name of a screen color or intensity. is a keyword to specify a Boolean expression. is a Boolean expression. If it is TRUE, text in the eld is displayed with the dispmode attribute.

dispmode
WHERE

condition

Notes
1. The condition can be a Boolean expression of the following forms: expr [ NOT ] IN (expr [ , expr . . . ] ) expr [ NOT ] BETWEEN expr AND expr expr [ NOT ] LIKE expr [ ESCAPE "char"] expr [ NOT ] MATCHES expr [ ESCAPE "char"] bool-expr [ AND | OR ] bool-expr for relop a relational operator ( = <> != > >= <= < ); bool-expr a Boolean expression; and expr the current eld-tag, a constant, or TODAY or CURRENT, arithmetic symbols, or the unary minus symbol: expr { + | - | * | / } expr - expr 2. In a condition, a eld tag evaluates to the current value in the eld. 3. If you do not specify a condition, the intensity and/or color in your dispmode list applies to the eld.
( expr )

expr relop expr expr IS [ NOT ] NULL ( bool-expr ) NOT bool-expr

4-26

Form Building and Compiling

COLOR

4. If condition is FALSE, the eld is displayed with default characteristics, rather than with the attribute specied by dispmode. (See Default Screen Attributes later in this chapter.) 5. The dispmode list can specify zero or one color name, and zero or more intensity names from these lists:
Color WHITE YELLOW MAGENTA RED CYAN GREEN BLUE BLACK Text Display White Yellow Magenta Red Cyan Green Blue Black Intensity BLINK * UNDERLINE * REVERSE LEFT Text Display Blinking Underlined Reverse (inverse) video Left-justied

* The only attributes available on systems where INFORMIXTERM = terminfo

Examples
This example species that eld text appears in red:
f000 = customer.customer_num, color = red;

The next lines specify various eld displays if conditions are TRUE:
f002 f003 f004 f005 = = = = manufact.manu_code, color = red WHERE f002 = "HRO"; customer.lname, color = red WHERE f003 LIKE "Quinn"; mytab.col6, color = green WHERE f004 < 10000; mytab.col9, color = blue reverse WHERE f005 IS NULL, color = yellow WHERE f005 BETWEEN 5000 and 10000, color = red blink WHERE f005 > 10000;

Related Attribute
REVERSE

Form Building and Compiling

4-27

COMMENTS

COMMENTS
Overview
You can use the COMMENTS attribute to cause INFORMIX-4GL to display a message on the Comment line at the bottom of the screen. The message is displayed when the cursor moves to the associated eld and is erased when the cursor moves to another eld.

Syntax
eld-tag = [ table. ] column, COMMENTS = "message" ;

Explanation
eld-tag table.column
COMMENTS =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword, followed by an equal ( = ) sign. is a character string enclosed in quotation marks.

message

Notes
1. The message must appear between quotation ( " ) marks on a single line of the form specication le. 2. The default position of the Comment line on the screen is line 23. You can reset this position with the OPTIONS statement. 3. The default position of the Comment line in a window is LAST. You can reset this position in the OPTIONS statement (if you want the new position in all windows) or in the ATTRIBUTE clause of the appropriate OPEN WINDOW statement (if you want the new position in a specic window). See Chapter 7 for a description of the OPTIONS and OPEN WINDOW statements of INFORMIX-4GL. 4. The most common application of the COMMENTS attribute is to give information or instructions to the user. This is particularly appropriate when the eld accepts only a limited set of values. (See the description of the INCLUDE attribute later in this section for details of how to specify a range or a list of acceptable values for data entry.)

4-28

Form Building and Compiling

COMMENTS

5. 4GL programs can use the same screen form to support distinct task (for example, data input and query by example). Do not specify the COMMENTS attribute in a eld description unless the message is appropriate to all of the tasks in which the message can appear. If the same eld requires a different message for various tasks, you should specify each message using the INFORMIX-4GL MESSAGE or DISPLAY statements, rather than in the form specication le.

Example
This eld description species a message for the Comment line. The message will appear when the screen cursor enters the eld that displays the rst name of a customer:
c2 = customer.fname, comments = "Please enter initial if available.";

Related Attribute
INCLUDE

Form Building and Compiling

4-29

DEFAULT

DEFAULT
Overview
Use the DEFAULT attribute to assign a default value to a display eld.

Syntax
eld-tag = [ table. ] column, DEFAULT = value;

Explanation
eld-tag table.column
DEFAULT =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword, followed by an equal ( = ) sign. is the default value.

value

Notes
1. Default values have no effect when you execute the INPUT statement using the WITHOUT DEFAULTS option. In this case, INFORMIX-4GL displays the values in the program variables list on the screen. The situation is the same for the INPUT ARRAY statement, except that INFORMIX-4GL displays the default values when you insert a new row. 2. If you use the WITHOUT NULL INPUT option in the DATABASE section and you do not use the DEFAULT attribute, then character elds default to blanks, number and INTERVAL elds to 0, and MONEY elds to $0.00. The default DATE value is 12/31/1899, and the DATETIME default value is 1899-12-31 23:59:59.99999. 3. If you do not use the WITHOUT NULL INPUT option in the DATABASE section, all elds default to NULL values unless you use the DEFAULT attribute. 4. If table is FORMONLY, you must specify a data type when you assign the DEFAULT attribute to a eld. (See the syntax in the section Form-Only Fields earlier in this chapter.) 5. For CHAR or DATE elds, enclose value in quotes ( " ).

4-30

Form Building and Compiling

DEFAULT

6. If the eld type is DATETIME or INTERVAL, you can enclose value in quotation ( " ) marks, or enter it as an unquoted literal:
DATETIME (values) qualier [ + | - ]INTERVAL (values) qualier

Here values and qualier are terms described in Appendix J. Besides these quoted and literal formats, a value of data type INTERVAL can also be specied in the format: expression UNITS eld Here expression can be a literal number, or the name of a number column or variable, or an expression in parentheses that evaluates to a number. UNITS is a keyword, and eld is a DATETIME element name, such as MONTH, DAY, HOUR, and so forth. (Here eld is neither a eld name nor eld tag.) 7. If both the DEFAULT attribute and the REQUIRED attribute are assigned to the same eld, the REQUIRED attribute is ignored. 8. Use the TODAY keyword as the value to assign the current date as the default value of a DATE eld. 9. Use the CURRENT keyword as the value to assign the current date and time as the default for a DATETIME eld.

Example
The following eld descriptions specify DEFAULT values:
c8 = state, UPSHIFT, AUTONEXT, DEFAULT = "CA"; o12 = order_date, DEFAULT = TODAY; f019 = formonly.timestamp TYPE DATETIME YEAR TO DAY COLOR = red, DEFAULT = CURRENT;

Form Building and Compiling

4-31

DISPLAY LIKE

DISPLAY LIKE
Overview
Use the DISPLAY LIKE attribute to display the eld by using the attributes assigned to a database column in the syscolatt table.

Syntax
eld-tag = [ table. ] column, DISPLAY LIKE tbl.col;

Explanation
eld-tag table.column
DISPLAY LIKE

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). are required keywords. is the name of a database column.

tbl.col

Notes
1. This attribute is equivalent to listing all the attributes that you have assigned to tbl.col in the syscolatt table. See the section Default Screen Attributes for details of the syscolatt table. 2. You do not need the DISPLAY LIKE attribute if table.column is the same as tbl.col. 3. Do not use a column of type DATETIME or INTERVAL for tbl.col.

Example
s12 = formonly.total, DISPLAY LIKE items.total_price;

Related Attribute
VALIDATE LIKE

4-32

Form Building and Compiling

DOWNSHIFT

DOWNSHIFT
Overview
Assign the DOWNSHIFT attribute to a character eld when you want INFORMIX-4GL to convert uppercase letters entered by the user to lowercase letters, both on the screen and in the corresponding program variable.

Syntax
eld-tag = [ table. ] column, DOWNSHIFT;

Explanation
eld-tag table.column
DOWNSHIFT

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or
FORMONLY).

is the keyword that instructs INFORMIX-4GL to convert character input data to lowercase letters in the program variable.

Note
Because uppercase and lowercase letters have different ASCII values, storing character strings in one or the other format can simplify sorting and querying a database.

Related Attribute
UPSHIFT

Form Building and Compiling

4-33

FORMAT

FORMAT
Overview
Use the FORMAT attribute with a DECIMAL, SMALLFLOAT, FLOAT, or DATE eld to control the format of output displays.

Syntax
eld-tag = [ table. ] column, FORMAT = " format-string" ;

Explanation
eld-tag table.column
FORMAT =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword, followed by an equal ( = ) sign. is a string of characters to specify a data format. You must enclose format-string in quotation marks.

format-string

Notes
1. For DECIMAL, SMALLFLOAT, or FLOAT data types, the format-string consists of pound signs (#) that represent digits, and a decimal point. For example, "###.##" produces at least three places to the left of the decimal point and exactly two to the right. 2. If the actual number displayed is shorter than the format-string, INFORMIX-4GL right justies it and pads the left with blanks. 3. If the format-string is smaller than the display width, FORM4GL gives a warning, but the form is usable. INFORMIX-4GL displays the data right justied in the eld. 4. If necessary to satisfy the format, INFORMIX-4GL rounds numbers before displaying them. 5. For DATE data types, INFORMIX-4GL recognizes the following symbols as special in the format-string: mm mmm produces the two-digit representation of the month. produces a three-letter abbreviation of the month; for example, Jan, Feb, and so on.

4-34

Form Building and Compiling

FORMAT

dd ddd yy yyyy

produces the two-digit representation of the day. produces a three-letter abbreviation of the day of the week; for example, Mon, Tue, and so on. produces the two-digit representation of the year. produces a four-digit year.

For dates, FORM4GL interprets any other characters as literals and displays them wherever you place them within format-string. 6. If FORMAT is an attribute of any eld name of a multiple-column eld, the eld uses the specied format-string regardless of which column is active.

Examples
For DATE elds:
Input no FORMAT attribute FORMAT = "mm/dd/yy" FORMAT = "mmm dd, yyyy" FORMAT = "yymmdd" FORMAT = "dd-mm-yy" FORMAT = "(ddd.) mmm. dd, yyyy" Result 09/15/1989 09/15/89 Sep 15, 1989 890915 15-09-89 (Sat.) Sep. 15, 1989

Related Attribute
PICTURE

Form Building and Compiling

4-35

INCLUDE

INCLUDE
Overview
Use the INCLUDE attribute to specify acceptable values for a eld, and to cause INFORMIX-4GL to check before accepting an input value.

Syntax
eld-tag = [ table. ] column, INCLUDE = ( { value | value TO value } [ , . . . ] );

Explanation
eld-tag table.column
INCLUDE =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword, followed by an equal ( = ) sign. is an element in a list (in parentheses) of individual values (value1, value2, . . . ), or a range of values (value1 TO value2), or any combination of individual values and ranges, separated by commas. is a keyword that separates the lower and upper limits of a range of values.

value

TO

Notes
1. If table is FORMONLY, you must specify a data type when you assign the INCLUDE attribute to a eld. (See the syntax in the section Form-Only Fields earlier in this chapter.) 2. When you specify a range of values, the lower value must appear rst. (Here lower means the number closer to zero or with the larger negative value; or the earlier DATE or DATETIME value; or the string that starts with a character closer to the beginning of the ASCII collating sequence.) 3. For ranges of character values, INFORMIX-4GL uses dictionary order within the printable ASCII character set. (See Appendix H for the ASCII collating sequence.) In a number eld, the range 5 TO 10 is acceptable. In a character eld, it is incorrect. The character string 10 is less than the string 5, since 1 comes before 5 in the ASCII character set.

4-36

Form Building and Compiling

INCLUDE

4. If you include a character string that contains a blank space, a comma, or any special characters, or does not begin with a letter, you must enclose the entire string in quotation marks. It is advisable to enclose character strings in quotation marks at all times. 5. The user must enter an acceptable value in any display eld with the INCLUDE attribute before INFORMIX-4GL accepts a new row. 6. If the list of acceptable values in the value-list does not include the default value, the INCLUDE attribute behaves like the REQUIRED attribute, and an acceptable entry is required. 7. Including a COMMENTS attribute to indicate acceptable values makes data entry easier.

Example
i18 = items.quantity, include = (1 to 50), comments = "Acceptable values are 1 through 50";

Related Attributes
COMMENTS, REQUIRED

Form Building and Compiling

4-37

NOENTRY

NOENTRY
Overview
Use the NOENTRY attribute to prevent data entry during an INPUT or INPUT ARRAY statement.

Syntax
eld-tag = [ table. ] column, NOENTRY;

Explanation
eld-tag table.column
NOENTRY

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is a keyword indicating that no data can be entered in the eld by an INPUT or INPUT ARRAY statement.

Note
The NOENTRY attribute does not prevent data entry into a eld during a CONSTRUCT statement (for a query by example).

Example
i13 = items.stock_num; = stock.stock_num, NOENTRY;

When you are entering data into the stock table, the stock_num column is not available, since this SERIAL column gets its value from INFORMIX-4GL during the INSERT statement. You can, however, use the same eld to enter the stock number intended for the items table.

4-38

Form Building and Compiling

PICTURE

PICTURE
Overview
Use the PICTURE attribute to specify the character pattern for data entry to a character eld.

Syntax
eld-tag = [ table. ] column, PICTURE = "format-string";

Explanation
eld-tag table.column
PICTURE =

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or
FORMONLY).

is a keyword, followed by an equal ( = ) sign. is a string of characters (enclosed in quotes) to specify the desired character pattern.

format-string

Notes
1. A format-string can include three special symbols:
Symbol A # X Meaning Any letter Any digit Any character

INFORMIX-4GL treats any other character in the format-string as a literal. The cursor skips over any literals during data entry.

2. INFORMIX-4GL displays the literal characters in the display eld and leaves blanks elsewhere. 3. The format-string must ll the entire width of the display eld. 4. If the user attempts to enter a character not in conformity with the format-string, the terminal beeps, and INFORMIX-4GL does not echo the character on the screen. 5. The PICTURE attribute does not require the entry of the entire eld. It only requires that whatever the user enters conforms to format-string.

Form Building and Compiling

4-39

PICTURE

6. When PICTURE formats DATETIME or INTERVAL elds, FORM4GL does not check the syntax of format-string, but your form will work if the syntax is correct. Any error in format-string, however, such as an incorrect eld separator, produces a run-time error.

Examples
The eld specication
c10 = customer.phone, picture = "###-###-####x#####";

produces the following display eld before data entry:

[ x ]

As another example, if you specify a eld for part numbers like this
f1 = part_no, picture = "AA#####-AA(X)"; INFORMIX-4GL accepts any of the following inputs: LF49367-BB(*) TG38524-AS(3) YG67489-ZZ(D)

The user does not enter the - or the parentheses, but INFORMIX-4GL includes them in the string that it passes to the program variable.

Related Attribute
FORMAT

4-40

Form Building and Compiling

REQUIRED

REQUIRED
Overview
Use the REQUIRED attribute to force data entry in a particular eld during an INPUT or INPUT ARRAY statement.

Syntax
eld-tag = [ table. ] column, REQUIRED;

Explanation
eld-tag table.column
REQUIRED

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or
FORMONLY).

is the keyword that instructs INFORMIX-4GL to insist upon data entry to the eld-tag eld.

Notes
1. The REQUIRED keyword is effective only when table.column occurs in the list of screen elds of an INPUT or INPUT ARRAY statement. 2. There is no default value for a REQUIRED eld. If you assign both the REQUIRED attribute and the DEFAULT attribute to the same eld, INFORMIX-4GL assumes that the DEFAULT value satises the REQUIRED attribute. 3. The REQUIRED attribute requires only that the user enter a printable character in the eld. If the user subsequently erases the entry during the same input, INFORMIX-4GL considers the REQUIRED attribute satised. If you want to insist on a non-NULL entry, make the eld form-only and NOT NULL.

Example
If your ATTRIBUTES section includes the eld description
o20 = orders.po_num, REQUIRED; INFORMIX-4GL requires the entry of a purchase order value when you collect information for a new order. Form Building and Compiling 4-41

REQUIRED

Related Attribute
NOENTRY

4-42

Form Building and Compiling

REVERSE

REVERSE
Overview
Assign the REVERSE attribute to elds that you want INFORMIX-4GL to display in reverse video (dark characters in a bright eld).

Syntax
eld-tag = [ table. ] column, REVERSE;

Explanation
eld-tag table.column
REVERSE

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or
FORMONLY).

is the keyword that instructs INFORMIX-4GL to display the eld-tag eld in reverse video.

Notes
1. On terminals that do not support reverse video, elds having the REVERSE attribute are enclosed in angle brackets ( < > ) . 2. If REVERSE is an attribute of any eld name of a multiple-column eld, the eld is displayed in reverse video, regardless of which column is active.

Example
f000 = customer.customer_num, reverse;

Related Attribute
COLOR

Form Building and Compiling

4-43

UPSHIFT

UPSHIFT
Overview
Assign the UPSHIFT attribute to a character eld when you want INFORMIX-4GL to convert lowercase letters in data entry to uppercase letters, both on the screen and in the program variable corresponding to that eld.

Syntax
eld-tag = [ table. ] column, UPSHIFT;

Explanation
eld-tag table.column
UPSHIFT

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). is the keyword that instructs INFORMIX-4GL to convert character input data to uppercase.

Note
Because uppercase and lowercase letters have different ASCII values, storing all character strings in one or the other format can simplify sorting and querying a database.

Example
c8 = state, UPSHIFT, AUTONEXT, INCLUDE = ("CA", "OR", "NV", "WA"), DEFAULT = "CA" ;

Because of the UPSHIFT attribute, INFORMIX-4GL enters uppercase characters in the state eld regardless of the case used to enter them. The AUTONEXT attribute tells INFORMIX-4GL to move automatically to the next eld once you type the total number of characters allowed for the eld (in this instance, two characters). The INCLUDE attribute restricts entry in this eld to the characters CA, OR, NV, or WA only. The DEFAULT value for the eld is CA.

4-44

Form Building and Compiling

UPSHIFT

Related Attribute
DOWNSHIFT

Form Building and Compiling

4-45

VALIDATE LIKE

VALIDATE LIKE
Overview
Use the VALIDATE LIKE attribute to cause INFORMIX-4GL to validate the data entered into the eld, using the default attributes assigned to a database column in the syscolval table.

Syntax
eld-tag = [ table. ] column, VALIDATE LIKE tbl.col;

Explanation
eld-tag table.column
VALIDATE LIKE

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or FORMONLY). are required keywords. is the name of a database column

tbl.col

Notes
1. This attribute is equivalent to listing all the attributes that you have assigned to tbl.col in the syscolval table. A later section, Default Screen Attributes, describes the syscolval table. 2. You do not need the VALIDATE LIKE attribute if table.column is the same as tbl.col. 3. Do not use columns of type DATETIME or INTERVAL for tbl.col.

Example
s13 = formonly.state, VALIDATE LIKE customer.state;

Related Attribute
DISPLAY LIKE

4-46

Form Building and Compiling

VERIFY

VERIFY
Overview
Use the VERIFY attribute when you want INFORMIX-4GL to require users to enter data twice for a particular eld, in order to reduce the probability of erroneous data entry.

Syntax
eld-tag = [ table. ] column, VERIFY;

Explanation
eld-tag table.column
VERIFY

is the eld tag used in the SCREEN section. is the name of a eld (either related to a column or
FORMONLY).

is the keyword that instructs INFORMIX-4GL to require duplicate data entry to the eld-tag eld.

Note
Since some data are critical, this attribute supplies an additional step in data entry to ensure the integrity of your data. After the user enters a value into a VERIFY eld and presses RETURN, INFORMIX-4GL erases the eld and requests reentry of the value. The user must enter exactly the same data each time, character for character: 15000 is not exactly the same as 15000.00.

Example
If you specify a eld for salary information like this:
s10 = quantity, VERIFY; INFORMIX-4GL requires the entry of exactly the same data twice.

Form Building and Compiling

4-47

WORDWRAP

WORDWRAP
Overview
Use the WORDWRAP attribute in a multiple-line eld to enable the multiline editor. This attribute wraps a long character string to the next line of a multiple-line eld for data entry and display.

Syntax
eld-tag = [ table. ] column, WORDWRAP [ COMPRESS ] ;

Explanation
eld-tag table.column
WORDWRAP COMPRESS

is the eld tag used in the SCREEN section. is the name of a multiple-line eld (either related to a column or FORMONLY). is a keyword to wrap long character strings to the next segment of a multiple-line eld. is a keyword to discard any blank spaces that the user did not enter and that are not part of the data.

Notes
1. When a 4GL program uses a multiple-line eld to display output, the data is poured out into the segments of the multiple-line eld, in left-to-right and top-to-bottom order. 2. When text is entered into a multiple-line eld whose attributes include WORDWRAP, the multiline editor breaks character strings into segments at blanks (if it can), padding eld segments with blanks at the right. Where possible, contiguous non-blank substrings (here called words) within a string are not broken at display line boundaries. 3. When keyboard input reaches the end of a line, the multiline editor brings the current word down to the next line, moving text down to subsequent lines as necessary. When the user deletes text, the editor pulls words up from lower lines whenever it can. 4. Text in WORDWRAP elds can have printable ASCII characters, the TAB, and NEWLINE. These are retained in the program variable. The TAB character aligns the display at the next tab stop, while NEWLINE moves
4-48 Form Building and Compiling

WORDWRAP

5.

6.

7.

8.

9.

10. 11.

the display to the start of the next line. Tab stops are in every eighth column, beginning at the left-hand edge of the eld. Ordinarily, the length of the variable should not be greater than the total length of the eld. When the data is longer than the eld (or if too much padding is required for WORDWRAP), the multiline editor lls the eld and discards the excess data. This allows a long variable to be shown in summary form. If a truncated variable is used to update the database, however, data will be lost. The editor distinguishes between intentional blanks (from the database or typed by the user) and editor blanks (inserted at the ends of lines for wordwrap or to align after a NEWLINE). Intentional blanks are retained as part of the data. Editor blanks are inserted and deleted automatically as required for word-wrapping. When designing a multiple-line eld, you should allow room for editor blanks, over and above the variable length. The expected number of editor blanks is half the length of an average word per line. Text that requires more space than you expect might be truncated after the nal line of the eld. The COMPRESS keyword prevents blanks produced by the editor from being included in the program variable. If you specify COMPRESS, truncation occurs only if the sum of intentional characters exceeds the column size. But the stored data does not correspond to its multiline display, so a report cannot display it in identical form. If you omit COMPRESS, all blanks are retained in the variable, even editor blanks, and the contents of a variable reect its multiline display. For example, a report could duplicate its appearance by printing successive substrings the width of a display segment. If the sum of the eld segment lengths exceeds the length of the variable, some trailing characters might be truncated. An earlier section, Multiple-Line Fields, describes the SCREEN section specications for multiple-line elds. When data is entered or updated in a WORDWRAP eld, the user can use keys that are described in this note to move the screen cursor over the data, and to insert, delete, and type over the data. The cursor never pauses on editor blanks. The editor has two modes, insert (to add data at the cursor) and typeover (to replace existing data with entered data). You cannot overwrite a NEWLINE. If the cursor in typeover mode encounters a NEWLINE character, the cursor mode automatically changes to insert, pushing the NEWLINE character to the right. Some keystrokes behave differently in the two modes.
Form Building and Compiling 4-49

WORDWRAP

When the cursor rst enters a multiline eld, it is positioned on the rst character of the rst segment, and the mode is set to typeover. The cursor movement keys are as follows:
RETURN BACKSPACE

leaves the entire multiline eld, and goes to the rst character of the next eld. moves left one character, unless at the left edge of a segment. From the left edge of the rst segment, these either move to the rst character of the preceding eld, or only beep, depending on input wrap mode. (Input wrap mode is controlled by the OPTIONS statement.) From the left edge of a lower segment, these move to the rightmost intentional character of the next higher segment. moves right one character, unless at the rightmost intentional character in a segment. From the rightmost intentional character of the last segment, this either moves to the rst character of the next eld, or only beeps, depending on input wrap mode. From the rightmost intentional character of a higher segment, this moves to the rst intentional character in a lower segment. moves from the topmost segment to the rst character of the preceding eld. From a lower segment, this moves to the character in the same column of the next higher segment, jogging left, if required, to avoid editor blanks, or if it encounters a TAB. moves from the lowest segment to the rst character of the next eld. From a higher segment, moves to the character in the same column in the next lower segment, jogging left if required to avoid editor blanks, or if it encounters a TAB. inserts a TAB character, in insert mode, and moves the cursor to the next TAB stop. This can cause following text to jump right to align at a TAB stop. In typeover mode, this moves the cursor to the next TAB stop that falls on an intentional character, going to the next eld segment if required.

or
LEFT ARROW

RIGHT ARROW

UP ARROW

DOWN ARROW

TAB

The character keys enter data. Any following data shifts right, and words can move down to subsequent segments. This can result in characters

4-50

Form Building and Compiling

WORDWRAP

being discarded from the nal segment of the eld. The other keystrokes that alter data are:
CONTROL-A CONTROL-X CONTROL-D

switches between typeover and insert mode. deletes the character under the cursor, possibly causing words to be pulled up from subsequent segments. deletes all text from the cursor to the end of the multiple-line eld (not merely to the end of the current eld segment). inserts a NEWLINE character, causing subsequent text to align at the rst column of the next segment of the eld, and possibly moving words down to subsequent segments. This can result in characters being discarded from the nal segment of the eld.

CONTROL-N

12. The appearance on the screen of a character value can vary, depending on whether or not it is displayed in a multiple-line WORDWRAP eld. For instance, if a value prepared using WORDWRAP is displayed without it, words will be broken, not wrapped, and tabs and newlines will display as question marks. This does not represent any loss of data, only a different mode of display. If a value prepared under the multiline editor is again edited without WORDWRAP, however, some formatting may be lost. For example, a user might type over a TAB or NEWLINE, not realizing what it was. A user might remove a blank from the rst column of a line, and thus join a word to the last word on the previous line. These mistakes will be visible when the value is next displayed in a WORDWRAP eld or in a 4GL report that uses the WORDWRAP function. 13. If you also have INFORMIX-SQL installed on your system, you can use the SQL Interactive Editor to display character data that you prepared using WORDWRAP. Since the default screen display of the Interactive Editor does not wrap words, words will appear broken, not wrapped, and TAB and NEWLINE characters will appear as question marks ( ? ). This does not represent any loss of data, only a different mode of display.

Form Building and Compiling

4-51

INSTRUCTIONS Section

Example
In the following form specications, a CHAR value in the column charcolm is displayed in the multiple-line eld whose tag is mlf.
SCREEN SIZE 24 by 80 { Enter text: [mlf ] [mlf ] . . . [mlf ] [mlf ] } TABLES tablet . . .

ATTRIBUTES mlf = tablet.charcolm, WORDWRAP COMPRESS;

If the data string is too long to t in the rst line, successive segments will be displayed in successive lines, until all of the lines are lled, or until the last text character is displayed (whichever happens rst). If the form is used to insert data into tablet.charcolm, the keyword COMPRESS species that INFORMIX-4GL will not store editor blanks. Do not use a comma between the keywords WORDWRAP and COMPRESS. Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

INSTRUCTIONS Section
The INSTRUCTIONS section is the optional nal section of a form specication le. You can use this section to specify non-default eld delimiters, and to dene screen records and screen arrays. It appears after the last eld description (or after the optional END keyword) of the ATTRIBUTES section. It has this structure:

Syntax
INSTRUCTIONS { delimiters | record | array } ... [ END ] 4-52 Form Building and Compiling

INSTRUCTIONS Section

Explanation
INSTRUCTIONS

is a required keyword to mark the beginning of the INSTRUCTIONS section. species two non-default screen eld delimiters. species a screen record. species an array of screen records. is an optional keyword to mark the end of the INSTRUCTIONS section.

delimiters record array

END

Notes
1. Specify no more than one delimiters instruction. 2. The END keyword is optional and can be omitted. The pages that follow describe these three types of instructions.

Field Delimiters
You can change the delimiters that INFORMIX-4GL uses to enclose elds when the form appears on the screen from brackets ( [ ] ) to any other printable character, including blank spaces.

Syntax
DELIMITERS "ab"

Explanation
DELIMITERS

is a keyword to specify eld delimiters. is the opening eld delimiter. is the closing eld delimiter.

a b

Notes
1. The DELIMITERS instruction tells INFORMIX-4GL what symbols to use as eld delimiters when it displays the form on the screen. 2. FORM4GL requires brackets ( [ ] ) in the SCREEN section of a form specication le, regardless of any DELIMITERS instruction. 3. You must enclose the pair of ab symbols in quotation ( " ) marks.

Form Building and Compiling

4-53

INSTRUCTIONS Section

4. Each delimiter occupies a space, so two elds on the same line are ordinarily separated by at least two spaces. If you want only one space between consecutive screen elds, follow these two steps: (1) In the SCREEN section, substitute a vertical bar ( | ) for paired back-to-back ( ][ ) brackets that separate adjacent elds. (2) In the INSTRUCTIONS section, dene some symbol as both the beginning and ending delimiter. For example, you could specify "| |" or "/ /" or ": :" or " " (blanks).

Examples
The following specications display < and > as opening and closing delimiters of screen elds:
INSTRUCTIONS DELIMITERS "<>" END

The following specications substitute | for ][ between adjacent elds in the same line of the screen layout, and display a colon ( : ) as both the opening and closing delimiter:
SCREEN { . . . Full Name-[f011 . . . } . . . INSTRUCTIONS DELIMITERS "::" |f012 ]

Here the elds whose tags are f011 and f012 will be displayed as:
Full Name-: | :

If you substitute blanks for colons as DELIMITERS symbols, eld boundaries are not marked (or are only marked if they have attributes that contrast with the surrounding background).

4-54

Form Building and Compiling

INSTRUCTIONS Section

Screen Records
You can collect groups of screen elds into screen records. Dene any screen records in the INSTRUCTIONS section of a form specication le, and refer to them in your INFORMIX-4GL program.

Syntax
SCREEN RECORD record-name ( { table.* | table.column1 THRU table.column2 | table.column } [ , . . . ] )

Explanation
SCREEN RECORD

are keywords to dene a list of elds as a screen record or as a screen array. is an SQL identier for the screen record. is a table name, alias, or synonym (or the keyword
FORMONLY).

record-name table column1, column2, column

THRU

are eld names that you dened in the ATTRIBUTES section. (These identiers link the elds to database columns, unless you specify table as FORMONLY.) is an optional keyword to specify consecutive elds. The keyword THROUGH is a synonym.

Notes
1. A screen record or screen array can include elds with different table specications, including FORMONLY. 2. FORM4GL automatically creates a default screen record for each table that is used to identify a eld in the form specication le. The default record, which has the name of the table, contains components corresponding to only those columns in the table that are elds on the form. The order of components in a screen record is the order of the eld names in the ATTRIBUTES section. Use table.* to denote the same elds as the default record for table. 3. FORM4GL returns an error if you dene a screen record with the same name as a table in the form. 4. The option of giving a range of eld names with the THROUGH (or THRU) keyword assumes the order in which the elds are listed in the ATTRIBUTES section. The THRU keyword is shorthand for listing all elds
Form Building and Compiling 4-55

INSTRUCTIONS Section

that appear in the ATTRIBUTES section from column1 to column2, inclusive.

Examples
This example creates a screen record called address from elds linked to some columns of the customer table. This record can simplify 4GL statements to update customer address and telephone data.
SCREEN RECORD address (customer.address1 THRU customer.phone)

All the elds linked to columns from the customer table constitute a default screen record whose record-name is customer.

Screen Arrays
You can collect groups of screen elds into screen arrays. A screen array is usually an array of lines on the form, each containing identical groups of screen elds. Each column of a screen array consists of elds with the same tag. Dene screen arrays in the INSTRUCTIONS section, and refer to them in your INFORMIX-4GL program.

Syntax
SCREEN RECORD record-name [ n ] ( { table.* | table.column1 THRU table.column2 | table.column } [ , . . . ] )

Explanation
Syntax terms are the same as for screen records on the previous page, with the addition of [ n ] as a required integer parameter, enclosed in brackets. (In this context, the brackets are required, and do not signify an optional syntax.)

Notes
1. The integer n species the number of rows in the screen array. 2. You can reference record-name in the DISPLAY, DISPLAY ARRAY, INPUT, and INPUT ARRAY statements of INFORMIX-4GL.

4-56

Form Building and Compiling

Default Screen Attributes

Example
To illustrate a typical screen array, consider the following fragment of a form specication le:
SCREEN { ... Item 1 Item 2 Item 3 Item 4 Item 5 }

[p [p [p [p [p

][q ][q ][q ][q ][q

][u ][u ][u ][u ][u

][t ][t ][t ][t ][t

] ] ] ] ]

TABLES orders items stock ATTRIBUTES ... p = stock.stock_num; q = items.quantity; u = stock.unit_price; t = items.total_price; ... INSTRUCTIONS SCREEN RECORD sc_items[5] (stock.stock_num, items.quantity, stock.unit_price, items.total_price)

The sc_items screen array has ve rows and four columns and includes elds linked to columns from two database tables. The rows are numbered from 1 to 5. If there are no other columns of the items table in the form, the default screen record items contains two elds, corresponding to the quantity and total_price columns of the items table.

Default Screen Attributes

As an alternative to entering attributes in the form specication le, you can enter them into two database tables, syscolval and syscolatt, using the upscol utility described in Appendix E. During compilation of a form, FORM4GL searches these tables for data validation and screen attribute information about screen elds whose names correspond to database columns. FORM4GL adds the attributes listed in these tables to attributes listed in the form specication le. In case of conict, attributes explicitly mentioned in the form specication le take priority.

Form Building and Compiling

4-57

Default Screen Attributes

INFORMIX-4GL enforces the resulting set of eld attributes during the execution of the INPUT and INPUT ARRAY statements (by using syscolval), and during DISPLAY and DISPLAY ARRAY statements (by using syscolatt).

The schemas of these tables follow:

syscolval tabname char(18) colname char(18) attrname char(10) attrval char(64) syscolatt tabname char(18) colname char(18) seqno serial color smallint inverse char(1) underline char(1) blink char(1) left char(1) def_format char(64) condition char(64)

Here tabname and colname are the names of the table and column to which the attributes apply. Here colname cannot be a DATETIME or INTERVAL column. Permissible values for the attrname and attrval columns in syscolval are shown in the following table:
attrname INCLUDE PICTURE DEFAULT COMMENTS SHIFT VERIFY AUTONEXT attrval as in this chapter as in this chapter as in this chapter as in this chapter UP, DOWN, NO (the default) YES, NO (the default) YES, NO (the default)

The color column in syscolatt stores an integer that describes color (for color terminals) or intensities (for monochrome terminals). The next table shows the displays specied by each value of color, and the correspondence between default color names and intensities.
Number 0 1 2 3 4 5 6 7 Color Terminal White Yellow Magenta Red Cyan Green Blue Black Monochrome Terminal Normal Bold Bold Bold Dim Dim Dim Invisible

4-58

Form Building and Compiling

Default Screen Attributes

The background for colors is BLACK in all cases. The signies that, if the keyword BOLD is indicated as the attribute, the eld will be RED on a color terminal; or, if the keyword DIM is indicated as the attribute, the eld will be BLUE on a color terminal. You can also dene non-default names for colors, by associating different names with the color number codes in a le named colornames. Appendix I describes the format of the colornames le. If this exists in $INFORMIXDIR/incl (see Appendix C), INFORMIX-4GL examines colornames at compile time to obtain the correspondence between the numbers 0 through 7 and the color names. Those names can appear in the ATTRIBUTE clause of a 4GL statement. (But you cannot use numbers or nondefault colors from colornames to specify the COLOR attribute in a form specication le.) The values for inverse, underline, and blink are Y (yes) and N (no). The default for each of these columns is N, that is, normal display (bright characters in a dark eld), no underline, and steady font. Which of these attributes can be displayed simultaneously with the color combinations or with each other is terminal-dependent. The def_format column takes the same string that you would enter for the FORMAT attribute in a screen form. Do not use quotation marks. The condition column takes string values that are a restricted set of the WHERE clauses of a SELECT statement, except that the WHERE keyword and the column name are omitted. INFORMIX-4GL assumes that the value in the column identied by tabname and colname is the subject of all comparisons. Examples of permitted entries for the condition column follow:
<= 100 BETWEEN 101 AND 1000 >= 1001 MATCHES "[A-M]*" IN ("CA", "OR", "WA") NOT LIKE "%analyst%"

The VALIDATE statement checks a program record or variable list against syscolval. The INITIALIZE statement looks up the default values that are listed in the syscolval table, and assigns them to variables. Some 4GL statements, including CONSTRUCT, DISPLAY, DISPLAY ARRAY, INPUT, INPUT ARRAY, and OPTIONS, support an ATTRIBUTE clause that can specify these attributes:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

Form Building and Compiling

4-59

The upscol Tables in a MODE ANSI Database

On color terminals, NORMAL is interpreted as WHITE; BOLD as RED; DIM as BLUE; and INVISIBLE as BLACK. If you have a colornames le, you can also use the color names or numbers listed there. You can override the default attributes in syscolatt by assigning other attributes in the form specication le, or in the ATTRIBUTE clause of the INFORMIX-4GL CONSTRUCT, DISPLAY, DISPLAY ARRAY, INPUT, or INPUT ARRAY statement. When one of these is the current statement and includes an ATTRIBUTE clause, INFORMIX-4GL displays only the attributes in that clause. There is no carry-over of unmentioned display attributes from the compiled form (except FORMAT). For example, if a column is designated as RED and BLINK in syscolatt, and your 4GL program executes the statement DISPLAY . . . ATTRIBUTE BLUE the eld has only the BLUE attribute. You do not get blinking BLUE. As stated earlier, form specication le attributes take precedence over the default syscolatt attributes. A note describing the OPTIONS statement in Chapter 7 lists the order of precedence among different sources of attribute specications, if these are in conict. Unconditional color or intensity attributes are available through the ATTRIBUTE clause. These and conditional attributes are also supported by syscolatt and by the COLOR keyword in the ATTRIBUTES section. You can use the upscol utility, described in Appendix E, to specify default attributes in syscolval and syscolatt. The color, intensity, and other screen attributes interact with termcap or terminfo les on UNIX systems. Appendix I describes the changes that should be made in system information les to support these display features for your terminal. Systems that use terminfo les rather than termcap, however, support no INFORMIX-4GL display attributes except REVERSE and UNDERLINE.

The upscol Tables in a MODE ANSI Database

In a database that is not MODE ANSI, the default screen attributes and validation criteria that you specify with the upscol utility are stored in two tables, syscolval and syscolatt. If any user of upscol assigns default values or attributes to a database column, those defaults are available to every user of a form that references the column.

4-60

Form Building and Compiling

Creating and Compiling a Form

In a database that is started or created as MODE ANSI, however, separate owner.syscolval and owner.syscolatt tables are created for each user of the upscol utility. These tables store the default specications of that individual user. Which set of upscol tables is used by FORM4GL depends on the nature of the request. If the TABLES section species a table alias for owner.table, FORM4GL uses the upscol tables of the owner of table. If that user owns no upscol tables, no defaults are assigned to elds associated with that table alias. If the TABLES section of the form does not specify a table alias that includes the owner of a database table, the upscol tables owned by the user running FORM4GL are applied to elds associated with that database table, unless the user owns no upscol tables. In the ATTRIBUTES section, specications of the form
eld-tag = . . . DISPLAY LIKE table.column eld-tag = . . . VALIDATE LIKE table.column

use upscol tables (if they exist) owned by the user who runs FORM4GL, unless table is an alias that species a different owner. If table is an alias for owner.table, FORM4GL uses the upscol tables of the owner specied by table. If the upscol tables do not exist, the statements take no action. If owner is not the correct owner, the compilation fails and an error message is issued. See also the notes in Chapter 7 on the VALIDATE and INITIALIZE statements of INFORMIX-4GL.

Creating and Compiling a Form

You can create a form specication le and its customized screen form either through the INFORMIX-4GL Programmers Environment or directly from the operating system. Either alternative requires that you have already created the database and all the tables to which the form refers. The next two subsections describe these alternative procedures.

Form Building and Compiling

4-61

Through the Programmers Environment

Through the Programmers Environment

To create a screen form using the Programmers Environment (which is described in Chapter 1), you must follow these steps: 1. At the system prompt, enter i4gl if you have the C Compiler Version, or r4gl if you have the Rapid Development System. 2. Select Form and then Generate from the menu. (Alternatively, you can select the New option. INFORMIX-4GL prompts you for a form name, prompts you for an editor if you have not already selected one, and invokes that editor with an empty form specication le. Now you must enter form specications. The Generate option is usually a more efcient way to create a customized form.) 3. Enter the name of the database and the name that you want to assign to the form (for example, myform). INFORMIX-4GL asks you for the names of the tables whose columns you want in your form. After you select the tables, FORM4GL creates a default form specication le, as well as a compiled default form, and then displays the FORM Design Menu. 4. The default form specication le formats the screen as a list of all the columns in the tables that you entered in Step 3. It does not provide any special instructions to INFORMIX-4GL about how to display the data. Select the Modify option, and INFORMIX-4GL presents the MODIFY FORM Screen. Select the default form specication (given as myform earlier), and INFORMIX-4GL calls a system editor to display the le. Edit the default form specication le to produce your customized screen form and associated instructions. (You can specify an editor using the DBEDIT environment variable. This is fully explained in Appendix C.) When you save your le and quit the editor, you return to the MODIFY FORM Menu. 5. Select Compile. If your form specication le successfully compiles, FORM4GL creates a form le with the extension .frm (for example, myform.frm). Go on to Step 7. If your form specication le does not compile successfully, go on to Step 6. 6. Select the Correct option from the COMPILE FORM Menu. INFORMIX-4GL again calls your editor to display the form specication le, with the compilation errors marked. When correcting your errors, you need not delete the error messages. INFORMIX-4GL does that for you. Save the le and go to Step 5. 7. Save your form specication le with the Save-and-exit option.

4-62

Form Building and Compiling

Through the Operating System

Through the Operating System

The FORM4GL command line has the following syntax:

Syntax
form4gl { [ -l lines ] [ -c cols ] [ -v ] form-name | -d }

Explanation
-l lines are optional symbols and an integer to specify the total number of lines of characters (measured vertically) that the terminal can display. (The default is 24.) are optional symbols and an integer to specify the width of the screen, in characters. (The default is the number of characters in the longest line of the screen layout, as specied in the SCREEN section.) are optional characters to verify that the screen elds are as wide as any corresponding character elds specied in the ATTRIBUTES section. is the name of the form specication le (without the .per extension). are optional symbols to specify a default form specication le.

-c cols

-v

form-name -d

To create a customized screen form directly from the operating system, follow these steps: 1. Create a default form specication le by entering the command
form4gl -d

at the operating system prompt. FORM4GL asks for the name of your form specication le, the name of your database, and the name of a table whose columns you want in your form. It continues to ask for another table name until you enter a RETURN for the name of a table. FORM4GL then creates a default form specication le and appends the extension .per to its name. It also creates a compiled default form with the extension .frm. 2. Use the system editor to modify the default form specication le to meet your specications. If, as an alternative, you create a new form specication le and skip Step 1, be sure to give the lename the extension .per.

Form Building and Compiling

4-63

Using PERFORM Forms in INFORMIX-4GL

3. Enter a command of the form:

form4gl myform

Here myform is the name of your form specication le (without the .per extension). If the compilation is successful, FORM4GL creates a compiled form le called myform.frm and you are nished creating your customized screen form. If not, FORM4GL instead creates a le named myform.err, and you need to go on to Step 4. 4. Review the le myform.err to discover the compilation errors. Make corrections in the le myform.per. Go to Step 3.

Using PERFORM Forms in INFORMIX-4GL

If you have designed forms to use with the PERFORM screen transaction program of INFORMIX-SQL, you need to know how those forms behave when used with INFORMIX-4GL. The following features differ between PERFORM and INFORMIX-4GL:

Only the DELIMITER keyword in the INSTRUCTIONS section of a

PERFORM form specication is supported in INFORMIX-4GL. Other

keywords in that section are ignored. For the same effects, you must code them into your INFORMIX-4GL program. (See the BEFORE and AFTER clauses of the INPUT statement.)

Multiple-page forms will not work with INFORMIX-4GL and will

produce undesirable overlays. (You can use multiple forms in 4GL to produce the effects of forms having several pages.)

There is no concept of current table in INFORMIX-4GL. A single INPUT

or INPUT ARRAY statement allows you to enter data into elds that correspond to columns in different tables.

Joins dened in the PERFORM form specication are ignored in INFORMIX-4GL. You can associate two eld names with the same eld tag, using the same notation as in a PERFORM join, but no join is effected. On the

other hand, you can create more complex joins and look-ups in INFORMIX-4GL using the full power of SQL.

The PERFORM attributes LOOKUP, NOUPDATE, QUERYCLEAR, RIGHT,

and ZEROFILL are inoperative in INFORMIX-4GL, and the conditions of a COLOR attribute cannot reference other eld tags nor aggregate functions.

The default attributes listed in syscolval and syscolatt do not apply

to your PERFORM forms unless you recompile them.
4-64 Form Building and Compiling

Chapter

Report Writing
Chapter Overview 3 Calling a REPORT Routine 4 Structure of a REPORT Routine 5 DEFINE Section 7 OUTPUT Section 9 REPORT TO 10 LEFT MARGIN 12 RIGHT MARGIN 13 TOP MARGIN 15 BOTTOM MARGIN 16 PAGE LENGTH 17 ORDER BY Section 18 FORMAT Section 20 EVERY ROW 21 Control Blocks 23 AFTER GROUP OF 25 BEFORE GROUP OF 27 FIRST PAGE HEADER 29 ON EVERY ROW 31 ON LAST ROW 33 PAGE HEADER 34 PAGE TRAILER 36 Statements 37 Standard 4GL Statements 37 Statements Valid Only in the FORMAT Section NEED 38 PAUSE 39 PRINT 40 PRINT FILE 42 SKIP 43 Expressions and Built-in Functions 44

5
37

Aggregates 46 LINENO 48 PAGENO 49 SPACES 50 WORDWRAP 51

5-2

Report Writing

Chapter Overview
INFORMIX-4GL provides all the tools of a general-purpose relational report writer. Reports in INFORMIX-4GL have the following features:

You have full control over page layout for your 4GL report. This includes
rst-page headers that differ from headers on subsequent pages, page trailers, columnar data presentation, special formatting before and after groups of sorted data, and conditional formatting that depends on the data.

INFORMIX-4GL provides aggregate functions that enable you to compute percentages, sums, averages, maximums, and minimums.

You can use the WORDWRAP function to display long character strings
that occupy multiple lines of output.

You can use all the built-in functions of INFORMIX-4GL and the USING
operator. (Chapter 2 describes USING and the built-in 4GL functions and expressions.)

You can create the report either from the rows returned by a cursor or
from report records assembled from any other source, such as the output of several different SELECT statements.

You can manipulate data returned by the cursor on a row-by-row basis,

either before or after the row is formatted by the report.

You can update the database or perform any other sequence of INFORMIX-4GL statements in the middle of writing a report if the intermediate values calculated by the report meet your criteria. For example, you could even write an alert message containing a second report.

This chapter describes the rules for calling and writing 4GL REPORT routines. (See also Chapter 9 of the INFORMIX-4GL User Guide for additional examples of REPORT routines.)

Report Writing

5-3

Calling a REPORT Routine

Calling a REPORT Routine

To call a REPORT routine requires three 4GL statements that occur before, during, and after a program loop that you dene. You can call a REPORT routine from the MAIN program block of a 4GL program or from a function, but a routine of type REPORT must be dened outside the MAIN program block
START REPORT report-name [ TO { PRINTER | PIPE program | lename } ] OUTPUT TO REPORT report-name ( variable-list ) FINISH REPORT report-name

The basic loop structure (whether a FOR, FOREACH, or WHILE loop) is illustrated as follows:
START REPORT report1 begin loop -- of whatever kind . . . OUTPUT TO REPORT report1(customer.*) . . . end loop FINISH REPORT report1

The START REPORT statement initializes the report and optionally

species the output le or device.

The OUTPUT TO REPORT statement tells INFORMIX-4GL to process the

next row of the report.

The FINISH REPORT statement causes the ON LAST ROW control block
to be executed, if it is present, so that INFORMIX-4GL can produce the end-of-report summaries. You can nd the full syntax for these statements in Chapter 7.

5-4

Report Writing

Structure of a REPORT Routine

Structure of a REPORT Routine

Like the MAIN program block or a function of a 4GL program, a report is a sequence of consecutive statements within a 4GL source le. A REPORT routine is composed of sections that consist of control blocks or statements, or both. Each statement can contain clauses made up of keywords and expressions. You must observe the order of the sections that follow when you write an INFORMIX-4GL REPORT routine.

DEFINE Section: This section declares the data types of any program variables or records that are passed as arguments to the report by the calling statement, and of any local variables or records that are used within the report. Reports that do not have such arguments or local variables do not require a DEFINE section. OUTPUT Section: This optional section species a non-default page

length and margins for the physical format of the report, and species whether INFORMIX-4GL sends the report to the screen, to a le, or to another program.

ORDER BY Section: This optional section species the variables on which you want rows to be sorted, and the order in which 4GL will process any group control blocks that you specify in the FORMAT section. FORMAT Section: This required section species the appearance of the

report, including page headers, page trailers, and aggregate functions of the data. Control blocks can specify actions to take before or after specic groups of rows are processed, using any INFORMIX-4GL statement, expression, or function. Control blocks can also include certain statements and functions that are only recognized within the FORMAT section of a REPORT routine. Each section begins with the keyword for which it is named. These elements of a REPORT routine are described in the pages that follow. The rst statement of a REPORT routine must be the REPORT statement, and the last must be the END REPORT statement:

Syntax
REPORT report-name (argument-list) [ DEFINE section ] [ OUTPUT section ] [ ORDER BY section ] FORMAT section END REPORT

Report Writing

5-5

Structure of a REPORT Routine

Explanation
REPORT

is a required keyword. is an INFORMIX-4GL identier.

report-name

(argument-list) is a list of variables or record identiers, enclosed in parentheses and separated by commas.
END REPORT

are required keywords.

Notes
1. Record identiers cannot have the asterisk ( .* ) extension in argument-list. 2. The DEFINE, OUTPUT, ORDER BY, and FORMAT sections are described in later sections of this chapter. 3. A minimal report consists only of the FORMAT section. You can include other sections as needed.

Examples
Several REPORT routines are included with the demonstration application listed in Appendix A. They illustrate many of the commands available for writing reports with INFORMIX-4GL, and provide some of the examples that appear in this chapter.

5-6

Report Writing

DEFINE Section

DEFINE Section
An INFORMIX-4GL REPORT routine requires a DEFINE section when you pass arguments to the report or use local variables in the report.

Syntax
DEFINE variable-list { type | LIKE table.column | RECORD { LIKE table.* | variable-list type [ , . . . ] END RECORD } } [ , . . . ]

Explanation
DEFINE

is a required keyword. is one or more identiers of program variable. is one of these data types (as dened in Chapter 2):
SMALLINT INTEGER INT DECIMAL [ (m [ , n ] ) ] DEC [ ( m [ , n ] ) ] NUMERIC [ (m [ , n ] ) ] SMALLFLOAT REAL RECORD [ LIKE table. * ] FLOAT [ ( n ) ] DOUBLE PRECISION [ ( n ) ] MONEY [ (m [ , n ] ) ] CHAR [ ( n ) ] CHARACTER [ (n ) ] DATE DATETIME qualier INTERVAL qualier

variable-list type

LIKE

is a keyword to specify the data type indirectly. is the full identier for a column in the current database. The DATABASE statement must precede DEFINE statements that use indirect typing. is a data type that describes a set of variables of possibly differing database data types. is the name of a database table. are keywords that follow the declaration of the last element of a program record.

table.column

RECORD

table
END RECORD

Report Writing

5-7

DEFINE Section

Notes
1. The DEFINE section obeys the same rules as given in Chapter 7 for the DEFINE statement, except that report parameters cannot be of type ARRAY, nor can they be records with ARRAY members. 2. The variable-list must include any local variables that you use in the report, and any variables or record identiers that appear in the argument-list of the REPORT statement. You are required to specify an argument-list if any of the following conditions are true:

When there is an ORDER BY section in your report. In this case, you

must pass all the values for each row of the report.

When you use the GROUP PERCENT aggregate function anywhere in

your report, or use an aggregate function over all the rows of the report at any place except in the ON LAST ROW control block. (In short, if you print an aggregate dependent on all rows of the report in the middle of the report, you must pass the rows of the report through the argument-list.)

When you use the FORMAT EVERY ROW control block. In this case,
you must pass all the values for each row of the report.

When you use the AFTER GROUP OF control block. In this case, you
must pass at least the parameters named in that block.

Example
REPORT r_invoice (c, stock_tot) DEFINE c RECORD LIKE customer.*, stock_tot SMALLINT

Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.

5-8

Report Writing

OUTPUT Section

OUTPUT Section
An INFORMIX-4GL REPORT routine can contain an OUTPUT section. This optional section controls the width of the margins and the length of the page, and allows you to direct the output from the report to a le, to a printer, or to an operating system pipe. The OUTPUT section consists of the OUTPUT keyword, followed by one or more statements. The OUTPUT section has this structure:
OUTPUT [ REPORT TO statement ] [ LEFT MARGIN statement ] [ RIGHT MARGIN statement ] [ TOP MARGIN statement ] [ BOTTOM MARGIN statement ] [ PAGE LENGTH statement ]

The REPORT TO statement species where to send output from the report
routine. If you omit this section, output is to the screen.

The LEFT MARGIN statement species how many blank spaces to include
at the left of each line of output. The default is 5 spaces.

The RIGHT MARGIN statement species the maximum number of characters in each line of output, including the left margin. The default is 132 characters.

The TOP MARGIN statement species how many blank lines appear
before the rst line on each page of output. The default is 3 lines.

The BOTTOM MARGIN statement species how many blank lines follow
the last line on each page of output. The default is 3 lines.

The PAGE LENGTH statement species the total number of lines on each
page of output, including lines of data, the top and bottom margins, and any page headers or page trailers that you dene in the FORMAT section. The default is 66 lines. The pages that follow describe these OUTPUT statements.

Report Writing

5-9

REPORT TO

REPORT TO
Overview
This optional statement directs the output of the INFORMIX-4GL report to a le, an operating system pipe, or the system printer.

Syntax
REPORT TO { "lename" | PIPE "program" | PRINTER }

Explanation
REPORT TO

are required keywords. is a quoted string containing the name of a le to receive the report. is an optional keyword. is a variable of type CHAR or a quoted string containing the name of a program that is to receive the output from the INFORMIX-4GL report. The program name, and any associated arguments, must be enclosed within quotation ( " ) marks. is an optional keyword.

lename
PIPE

program

PRINTER

Notes
1. You cannot use more than one of the REPORT TO options in a REPORT routine. When you do not use this optional statement, INFORMIX-4GL sends the report to your screen. 2. If the START REPORT statement has a TO clause directing output of the report to a le, pipe, or printer, INFORMIX-4GL ignores the REPORT TO statement of the OUTPUT section. 3. If lename is a variable, you must pass it as an argument to the REPORT routine. 4. The REPORT TO PRINTER statement causes INFORMIX-4GL to send the report to the program named by the DBPRINT environment variable. If you do not set this variable, INFORMIX-4GL sends the report to the lp program, or to whatever program is the default to access the system printer on your implementation of UNIX.
5-10 Report Writing

REPORT TO

5. If you want to send the report to a printer other than the system printer, you can use the REPORT TO lename option to send output to a le, and then send the le to a printer of your choice. You can also use the REPORT TO PIPE option to direct the output to a program that sends the output to the correct printer.

Examples
The following OUTPUT section directs the report output to the label.out system le.
OUTPUT REPORT TO "label.out" LEFT MARGIN 0 TOP MARGIN 0 BOTTOM MARGIN 0 PAGE LENGTH 6

The following OUTPUT section directs the output from the INFORMIX-4GL report to the more utility.
OUTPUT REPORT TO PIPE "more"

Report Writing 5-11

LEFT MARGIN

LEFT MARGIN
Overview
This statement sets a left margin for a report.

Syntax
LEFT MARGIN integer

Explanation
LEFT MARGIN

are required keywords. is an integer that species the width of the left margin, in spaces.

integer

Notes
1. The default left margin is ve spaces. 2. All columnar displacement indicated by the COLUMN function starts at the margin set by LEFT MARGIN.

Example
The following LEFT MARGIN statement instructs INFORMIX-4GL to print the left side of the report as far to the left as possible.
OUTPUT REPORT TO "label.out" LEFT MARGIN 0 TOP MARGIN 0 BOTTOM MARGIN 0 PAGE LENGTH 6

5-12

Report Writing

RIGHT MARGIN

RIGHT MARGIN
Overview
This statement sets a right margin for a report.

Syntax
RIGHT MARGIN integer

Explanation
RIGHT MARGIN

are required keywords. is an integer that species the width of the text on the page, in characters.

integer

Notes
1. The RIGHT MARGIN determines the right margin by specifying the width of the page, in characters. This is not dependent on the LEFT MARGIN, but always starts its count from the left edge of the page, so that the columns of the LEFT MARGIN are included in the value of RIGHT MARGIN. 2. The RIGHT MARGIN is effective only when the FORMAT section contains an EVERY ROW statement. 3. The default RIGHT MARGIN is 132 characters. 4. INFORMIX-4GL attempts to produce an EVERY ROW report by listing the variable names across the top of the page, and presenting the data in columns beneath these headings. If there is not sufcient room between the LEFT MARGIN and the RIGHT MARGIN to do this, INFORMIX-4GL produces a report that lists the variable names and the data of each row in two columns.

Report Writing

5-13

RIGHT MARGIN

Example
The following example demonstrates the use of the RIGHT MARGIN statement. After it processes the OUTPUT section, INFORMIX-4GL sets the right margin for the report at 70 characters.
REPORT simple(customer) DEFINE customer LIKE customer.* OUTPUT RIGHT MARGIN 70 FORMAT EVERY ROW END REPORT

5-14

Report Writing

TOP MARGIN

TOP MARGIN
Overview
This statement sets a top margin for a report.

Syntax
TOP MARGIN integer

Explanation
TOP MARGIN

are required keywords. is an integer that species the number of blank lines that INFORMIX-4GL leaves at the top of each page.

integer

Notes
1. The default top margin is three lines. 2. The top margin appears above any page header that you specify in the FORMAT section.

Example
The following TOP MARGIN statement instructs INFORMIX-4GL to begin printing at the top of each page.
OUTPUT REPORT TO "label.out" LEFT MARGIN 0 TOP MARGIN 0 BOTTOM MARGIN 0 PAGE LENGTH 6

Report Writing

5-15

BOTTOM MARGIN

BOTTOM MARGIN
Overview
This statement sets a bottom margin for a report.

Syntax
BOTTOM MARGIN integer

Explanation
BOTTOM MARGIN

are required keywords. is an integer that species the number of blank lines that INFORMIX-4GL is to leave at the bottom of each page.

integer

Notes
1. The default bottom margin is three lines. 2. The bottom margin appears below any page trailer.

Example
The following BOTTOM MARGIN statement instructs INFORMIX-4GL to continue printing to the bottom of each page.
OUTPUT REPORT TO "label.out" LEFT MARGIN 0 TOP MARGIN 0 BOTTOM MARGIN 0 PAGE LENGTH 6

5-16

Report Writing

PAGE LENGTH

PAGE LENGTH
Overview
This statement sets the number of lines on each page of a report.

Syntax
PAGE LENGTH integer

Explanation
PAGE LENGTH are required keywords.

integer

is an integer that species the length of the page, in lines.

Notes
1. The default page length is 66 lines. 2. The PAGE LENGTH includes both the TOP MARGIN and BOTTOM MARGIN.

Example
The following example includes a PAGE LENGTH statement:
OUTPUT PAGE LENGTH 22 TOP MARGIN 0 BOTTOM MARGIN 0

This example species that INFORMIX-4GL print each page with 22 lines. On a standard 24-line video screen, 22 lines is the maximum that you can use with the PAUSE statement without causing undesirable scrolling.

Report Writing

5-17

ORDER BY Section

ORDER BY Section
The optional ORDER BY section species variables on which to sort rows, and the order in which to process group control blocks in the FORMAT section. Its format is

Syntax
ORDER [ EXTERNAL ] BY sort-list

Explanation
ORDER BY EXTERNAL

are required keywords. is an optional keyword. is a list of one or more variables from the list of arguments to the REPORT routine.

sort-list

Notes
1. Include an ORDER BY section if your report uses group control blocks, and:

You have not sorted the input rows. You have already sorted the input rows, and you want to specify the
exact order in which the group control blocks are processed. (Without the ORDER BY section, INFORMIX-4GL chooses the order in which to process the group control blocks.) In this case, use the EXTERNAL keyword, so that the rows will not be sorted again. 2. The ORDER BY section species two things. First, it species the order in which INFORMIX-4GL orders the input rows. If sort-list contains a, b, and c in that order, then INFORMIX-4GL orders the input rows rst by a. Within that ordering, INFORMIX-4GL orders the rows next by b. Finally, INFORMIX-4GL orders the resulting sets of rows by the values of variable c. Second, the ORDER BY section species the order in which INFORMIX-4GL processes group control blocks. (See the section Control Blocks later in this chapter for more information.) 3. The EXTERNAL keyword in the ORDER BY section species that the input rows are already sorted. INFORMIX-4GL does not resort the rows in this case.

5-18

Report Writing

ORDER BY Section

4. If there is an ORDER BY section without the EXTERNAL keyword, INFORMIX-4GL makes two passes through the input data. During the rst pass, it sorts the data and stores it in a temporary le. During the second pass, it prints the report. If the input rows for your report come from the rows returned by only one cursor, you should use the ORDER BY clause in the SELECT statement associated with the cursor, and use the EXTERNAL keyword in the ORDER BY section of your report. 5. If you have just one variable named in group control blocks and the input rows are already sorted, then you do not need an ORDER BY section.

Example
REPORT r_invoice (c, stock_tot) DEFINE c RECORD LIKE customer.*, stock_tot SMALLINT ORDER BY stock_tot . . .

Report Writing

5-19

FORMAT Section

FORMAT Section
An INFORMIX-4GL REPORT routine must contain a FORMAT section. The FORMAT section determines what a report will look like. It works with the data that are passed to the routine through the argument list, or with data that you put in global variables for each row of the report. The FORMAT section begins with the FORMAT keyword, and ends with the END REPORT keywords. Two major types of FORMAT sections exist, both of which are described in the following sections. The simplest contains just one EVERY ROW statement between the FORMAT and END REPORT keywords. If you use an EVERY ROW statement, you cannot use any other statements or control blocks:

Syntax
FORMAT EVERY ROW END REPORT

More complex FORMAT sections can contain control blocks such as ON EVERY ROW and BEFORE GROUP OF. Each of these control blocks must contain at least one FORMAT statement such as PRINT or SKIP n LINES, and they can contain other statements. If you do not use an EVERY ROW statement, you can combine control blocks in any order within the FORMAT section. This type of non-default FORMAT section has the following structure:

Syntax
FORMAT [ PAGE HEADER control block ] [ PAGE TRAILER control block ] [ FIRST PAGE HEADER control block ] [ ON EVERY ROW control block ] [ ON LAST ROW control block ] [ BEFORE GROUP OF control block ...] [ AFTER GROUP OF control block ...] END REPORT

5-20

Report Writing

EVERY ROW

EVERY ROW
Overview
The EVERY ROW statement causes INFORMIX-4GL to output every row that you pass to the report. It uses a default format.

Syntax
EVERY ROW

Explanation
EVERY ROW

are required keywords.

Notes
1. The report consists of only the data that you pass to the routine through its arguments. 2. This statement is useful when you want to run a quick report using a default format. 3. The EVERY ROW statement stands by itself. You cannot modify it with any of the statements listed in the Statements section that appears later in this chapter. 4. When you use the EVERY ROW statement, you cannot use any control blocks in the FORMAT section. 5. A report generated by an EVERY ROW statement uses the variable names that you pass as arguments to the routine at run time as column headings. 6. If the variables passed as arguments t on a line, INFORMIX-4GL produces a report with variable names across the top of each page; otherwise, it produces a report with the variable names down the left side of the page. 7. You can use the RIGHT MARGIN statement in the OUTPUT section to control the width of a report that uses the EVERY ROW statement. 8. To display every row in a format other than the default format, use the ON EVERY ROW control block (discussed in the Control Blocks section later in this chapter.)

Report Writing

5-21

EVERY ROW

Examples
This minimal REPORT routine uses the EVERY ROW statement:
REPORT minimal(customer) DEFINE customer RECORD LIKE customer.* FORMAT EVERY ROW END REPORT

Here is a portion of the output from the preceding default specication.

customer.customer_num customer.fname customer.lname customer.company customer.address1 customer.address2 customer.city customer.state customer.zipcode customer.phone customer.customer_num customer.fname customer.lname customer.company customer.address1 customer.address2 customer.city customer.state customer.zipcode customer.phone . . . INFORMIX-4GL prints only the column name when the column contains a NULL value. 101 Ludwig Pauli All Sports Supplies 213 Erstwild Court Sunnyvale CA 94086 408-789-8075 102 Carole Sadler Sports Spot 785 Geary St San Francisco CA 94117 415-822-1289

Following is another example of a brief report specication that uses the EVERY ROW statement. Assume that the cursor used to FETCH rows for this report was DECLAREd with an ORDER BY.
REPORT simple(order_num, customer_num, order_date) DEFINE order_num LIKE orders.order_num, customer_num LIKE orders.customer_num, order_date LIKE orders.order_date FORMAT EVERY ROW END REPORT

5-22

Report Writing

Control Blocks

The following display shows the output from the preceding REPORT routine.
order_num customer_num order_date 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 104 101 104 106 116 112 117 110 111 115 104 117 104 106 110 01/20/1989 06/01/1989 10/12/1989 04/12/1989 12/04/1989 09/19/1989 03/25/1989 11/17/1989 02/14/1989 05/29/1989 03/23/1989 06/05/1989 09/01/1989 05/01/1989 07/10/1989

Control Blocks
Control blocks provide the structure for a customized report. Each control block is optional but, if you do not use the EVERY ROW statement, you must include at least one control block in a REPORT routine. Each control block must include at least one statement. (See the Statements section later in this chapter.) When you use the BEFORE GROUP OF, AFTER GROUP OF, and ON EVERY ROW control blocks in a single REPORT routine, INFORMIX-4GL processes all BEFORE GROUP OF blocks before the ON EVERY ROW block and the ON EVERY ROW block before all AFTER GROUP OF blocks. The order in which INFORMIX-4GL processes the BEFORE GROUP OF control blocks and AFTER GROUP OF control blocks depends upon the hierarchy of variables listed in the ORDER BY section or, in the absence of an ORDER BY section, implied by the order of rst mention of variables in either BEFORE or AFTER GROUP OF control blocks.

Report Writing

5-23

Control Blocks

Assume that the ORDER BY section orders by variables a, b, and c. Then the following display indicates the order by which INFORMIX-4GL processes control blocks:
BEFORE GROUP OF a BEFORE GROUP OF b BEFORE GROUP OF c ON EVERY ROW AFTER GROUP OF c AFTER GROUP OF b AFTER GROUP OF a Order of Group Processing

Figure 5-1

The pages that follow describe these control blocks in alphabetical order.

5-24

Report Writing

AFTER GROUP OF

AFTER GROUP OF
Overview
The AFTER GROUP OF control block species the action that INFORMIX-4GL takes after it processes a group of rows. Grouping is determined by the ordering that you did earlier.

Syntax
AFTER GROUP OF variable-name statement ...

Explanation
AFTER GROUP OF

are required keywords. is the name of one of the variables passed as an argument. is a FORMAT or INFORMIX-4GL statement.

variable-name statement

Notes
1. You must pass at least the value of variable-name through the arguments of the REPORT routine. 2. A group of rows is all rows that contain the same value for a given variable. INFORMIX-4GL automatically groups rows when you use an ORDER BY section in a REPORT routine, or the ORDER BY clause in a SELECT statement. That is, groups are formed when you order a list. When you specify more than one column in the ORDER BY section or clause, INFORMIX-4GL orders the rows rst by the rst variable that you specify (most signicant). Rows having the same value on the rst variable are then ordered by the second variable that you specify, and so on, until rows having the same value on all variables but the last are ordered by the last (least signicant) variable that you specify.
INFORMIX-4GL processes the statements in an AFTER GROUP OF control block each time the specied column changes value, each time a more signicant column changes value, and at the end of a report. (See Figure 5-1 at the beginning of the Control Blocks section.)

Report Writing

5-25

AFTER GROUP OF

3. You can have one AFTER GROUP OF control block for each variable on which you have ordered the data. 4. If you have an ORDER BY section and you have more than one AFTER GROUP OF control block, their order within the FORMAT section is not signicant. 5. When INFORMIX-4GL nishes generating a report, it executes all of the statements in the AFTER GROUP OF control blocks before it executes those in the ON LAST ROW control block. 6. Group aggregates can be used only in AFTER GROUP OF control blocks. You cannot use group aggregates in any other type of control block. 7. When INFORMIX-4GL processes the statements in an AFTER GROUP OF control block, the variables of the report still have the values from the last row of the group. From this perspective, the AFTER GROUP OF control block could be called the on last row of group control block.

Examples
AFTER GROUP OF r.order_num PRINT " ",r.order_date,7 SPACES, r.order_num USING "###&", 8 SPACES,r.ship_date," ", GROUP SUM(r.total_price) USING "$$$$,$$$,$$$.&&" AFTER GROUP OF r.customer_num PRINT 42 SPACES,"---------------" PRINT 42 SPACES,GROUP SUM(r.total_price) USING "$$$$,$$$,$$$.&&"

5-26

Report Writing

BEFORE GROUP OF

BEFORE GROUP OF
Overview
The BEFORE GROUP OF control block species the action that INFORMIX-4GL takes before it processes a group of rows. Grouping is determined by the ordering that you did earlier.

Syntax
BEFORE GROUP OF variable-name statement ...

Explanation
BEFORE GROUP OF

are required keywords. is the name of one of the variables passed as an argument. is an INFORMIX-4GL or FORMAT statement.

variable-name statement

Notes
1. You must pass at least the value of variable-name through the arguments of the REPORT routine. 2. A group of rows is all rows that contain the same value for a given variable. INFORMIX-4GL automatically groups rows when you use an ORDER BY section of a REPORT routine or the ORDER clause of a SELECT statement. That is, groups are formed when you order a list. When you specify more than one variable in an ORDER BY section or clause, INFORMIX-4GL orders the rows rst by the rst variable that you specify (most signicant), second by the second variable, and so on, until the last variable that you specify (least signicant) is ordered.
INFORMIX-4GL processes the statements in a BEFORE GROUP OF control block at the start of a report, each time the specied variable changes value, and each time a more signicant variable changes value. (See Figure 5-1 at the beginning of the Control Blocks section.)

3. You can have one BEFORE GROUP OF control block for each variable that you order.
Report Writing 5-27

BEFORE GROUP OF

4. If you have an ORDER BY section and you have more than one BEFORE GROUP OF control block, their order within the FORMAT section is not signicant. 5. When INFORMIX-4GL starts to generate a report, it executes all the statements in the BEFORE GROUP OF control blocks before it executes those in the ON EVERY ROW control block. 6. You can use a SKIP TO TOP OF PAGE statement in a BEFORE GROUP OF control block to cause each group to start at the top of a page. 7. When INFORMIX-4GL processes the statements in a BEFORE GROUP OF control block, the report variables have the values from the rst row of the new group. From this perspective, the BEFORE GROUP OF control block could be called the on rst row of group control block.

Example
BEFORE GROUP OF r.customer_num SKIP TO TOP OF PAGE

5-28

Report Writing

FIRST PAGE HEADER

FIRST PAGE HEADER

Overview
The FIRST PAGE HEADER control block can specify what information appears at the top of the rst page of the report.

Syntax
FIRST PAGE HEADER statement ...

Explanation
FIRST PAGE HEADER

are required keywords. is an INFORMIX-4GL or FORMAT statement.

statement

Notes
1. The TOP MARGIN (set in the OUTPUT section) affects how close to the top of the page INFORMIX-4GL displays the header. 2. The FIRST PAGE HEADER control block overrides a PAGE HEADER control block on the rst page of a report. 3. You cannot use the SKIP TO TOP OF PAGE statement in a FIRST PAGE HEADER control block. 4. If you use an IF THEN ELSE statement in a FIRST PAGE HEADER control block, the number of lines displayed by the PRINT statements following the THEN keyword must be equal to the number of lines displayed by the PRINT statements following the ELSE keyword. 5. You cannot use the PRINT lename statement to read and display text from a le in a FIRST PAGE HEADER control block. 6. You can use a FIRST PAGE HEADER control block to produce a title page, as well as column headings.

Report Writing

5-29

FIRST PAGE HEADER

Example
This example is from a report that produces multiple labels across the page.
FIRST PAGE HEADER {Nothing is displayed in this control block. It just initializes variables that are used in the ON EVERY ROW control block.} {Initialize label counter.} LET i = 1 {Determine label width (allow eight spaces total between labels).} LET l_size = 72/count1 {Divide the eight spaces between the number of labels across the page.} LET white = 8/count1

This FIRST PAGE HEADER does not display any information. Because INFORMIX-4GL executes the FIRST PAGE HEADER control block before it generates any output, you can use this control block to initialize variables that you use in the FORMAT section.

5-30

Report Writing

ON EVERY ROW

ON EVERY ROW
Overview
The ON EVERY ROW control block species the action to be taken by INFORMIX-4GL for every row of data that you pass to the routine.

Syntax
ON EVERY ROW statement ...

Explanation
ON EVERY ROW

are required keywords. is an INFORMIX-4GL or FORMAT statement.

statement

Notes
1. INFORMIX-4GL processes the statements in an ON EVERY ROW control block as each new row is formatted. 2. If a BEFORE GROUP OF control block is triggered by a change in column value, all appropriate BEFORE GROUP OF control blocks are executed (in the order of their signicance) before the ON EVERY ROW control block is executed. 3. If an AFTER GROUP OF control block is triggered by a change in column value, all appropriate AFTER GROUP OF control blocks are executed (in the reverse order of their signicance) after the ON EVERY ROW control block is executed.

Examples
The following example is from a report that lists all the customers, their addresses, and their telephone numbers across the page.
ON EVERY ROW PRINT customer_num USING "####", COLUMN 12, fname CLIPPED, 1 SPACE, lname CLIPPED, COLUMN 35, city CLIPPED, ", " , state, COLUMN 57, zipcode, COLUMN 65, phone Report Writing 5-31

ON EVERY ROW

The next example is from a mailing label report.

ON EVERY ROW IF (city IS NOT NULL) AND (state IS NOT NULL) THEN PRINT fname CLIPPED, 1 SPACE, lname PRINT company PRINT address1 IF (address2 IS NOT NULL) THEN PRINT address2 PRINT city CLIPPED ", " , state, 2 SPACES, zipcode SKIP TO TOP OF PAGE END IF

5-32

Report Writing

ON LAST ROW

ON LAST ROW
Overview
The ON LAST ROW control block species the action that INFORMIX-4GL is to take after it processes the last row passed to the REPORT routine and encounters the FINISH REPORT statement.

Syntax
ON LAST ROW statement ...

Explanation
ON LAST ROW are required keywords.

statement

is an INFORMIX-4GL or FORMAT statement.

Notes
1. INFORMIX-4GL executes the statements in the ON LAST ROW control block after it executes those in the ON EVERY ROW and AFTER GROUP OF control blocks. 2. When INFORMIX-4GL processes the statements in an ON LAST ROW control block, the columns that the report is processing still have the values from the nal row that the report processed. 3. The ON LAST ROW control block can display report totals.

Example
ON LAST ROW SKIP 1 LINE PRINT COLUMN 12, "TOTAL NUMBER OF CUSTOMERS:", COLUMN 57, COUNT(*) USING "##"

Report Writing

5-33

PAGE HEADER

PAGE HEADER
Overview
The PAGE HEADER control block species what information (if any) appears at the top of each page of the report.

Syntax
PAGE HEADER statement ...

Explanation
PAGE HEADER are required keywords.

statement

is an INFORMIX-4GL or FORMAT statement.

Notes
1. The TOP MARGIN (in the OUTPUT section) affects how close to the top of the page INFORMIX-4GL displays the page header. 2. The FIRST PAGE HEADER control block overrides a PAGE HEADER control block on the rst page of a report. 3. You cannot use the SKIP TO TOP OF PAGE statement in a PAGE HEADER control block. 4. The number of lines produced by the PAGE HEADER control block cannot change from page to page, and must be expressed unambiguously. The following rules are special cases of this general principle:

You cannot have a SKIP integer LINES statement inside a loop in the
PAGE HEADER control block.

You cannot use a NEED statement in the PAGE HEADER control block. If you use an IF THEN ELSE statement in a PAGE HEADER control
block, the number of lines displayed by the PRINT statements following the THEN keyword must be equal to the number of lines displayed by the PRINT statements following the ELSE keyword.

If you use a CASE, FOR, or WHILE statement that contains a PRINT

statement in a PAGE HEADER control block, you must terminate the print statement with a semicolon. The semicolon suppresses RETURNs
5-34 Report Writing

PAGE HEADER

in the loop, keeping the number of lines in the header constant from page to page.

You cannot use a PRINT lename statement to read and display text
from a le in a PAGE HEADER control block. 5. You can use a PAGE HEADER control block to display column headings in a report. 6. You can use the PAGENO expression in a PRINT statement within a PAGE HEADER control block to display the page number automatically at the top of every page.

Example
The following example produces the column headings for printing the customer data across the page.
PAGE HEADER PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "LOCATION", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE

Report Writing

5-35

PAGE TRAILER

PAGE TRAILER
Overview
The PAGE TRAILER control block species what information, if any, appears at the bottom of each page of the report.

Syntax
PAGE TRAILER statement ...

Explanation
PAGE TRAILER are required keywords.

statement

is an INFORMIX-4GL or FORMAT statement.

Notes
1. The BOTTOM MARGIN (in the OUTPUT section) affects how close to the bottom of the page INFORMIX-4GL displays the page trailer. 2. You cannot use the SKIP TO TOP OF PAGE statement in a PAGE TRAILER control block. 3. The number of lines produced by the PAGE TRAILER control block cannot change from page to page and must be unambiguously expressed. The following rules are special cases of this more general principle:

You cannot have a SKIP integer LINES statement inside a loop in the
PAGE TRAILER control block.

You cannot use a NEED statement in the PAGE TRAILER control block. If you use an IF THEN ELSE statement in a PAGE TRAILER control
block, the number of lines displayed by the PRINT statements following the THEN keyword must be equal to the number of lines displayed by the PRINT statements following the ELSE keyword.

If you use a CASE, FOR, or WHILE statement that contains a PRINT

statement in a PAGE TRAILER control block, you must terminate the PRINT statement with a semicolon. The semicolon suppresses

5-36

Report Writing

Statements

RETURNs in the loop, keeping the number of lines in the header con-

stant from page to page.

You cannot use a PRINT lename statement to read and display text
from a le in a PAGE TRAILER control block. 4. INFORMIX-4GL executes the PAGE TRAILER control block before the PAGE HEADER control block when you issue a SKIP TO TOP OF PAGE statement anywhere. 5. You can use the PAGENO expression in a PRINT statement within a PAGE TRAILER control block to display the page number automatically at the bottom of every page.

Example
PAGE TRAILER PRINT COLUMN 28, PAGENO USING "page <<<<"

Statements
The control blocks determine when INFORMIX-4GL takes an action in a report, while the statements determine what action INFORMIX-4GL takes. You can use any INFORMIX-4GL statement in a control block, as well as a number of statements that can be used only in the FORMAT section of a REPORT routine.

Standard 4GL Statements

The most common INFORMIX-4GL statements used in the control blocks of reports are FOR, IF, LET, and WHILE. These statements have the same syntax that they have elsewhere in 4GL applications, as described in Chapter 7. (Remember that any local variables referenced in such statements must be specied in the DEFINE section of the REPORT routine.)

Statements Valid Only in the FORMAT Section

There are ve statements that you can only use in the FORMAT section of a REPORT routine:
NEED PAUSE PRINT PRINT FILE SKIP

Descriptions of these FORMAT section statements follow.

Report Writing 5-37

NEED

NEED
Overview
This statement causes subsequent display to start on the next page if there is not the specied number of lines remaining on the current page.

Syntax
NEED num-expr LINES

Explanation
NEED

is a required keyword. is an expression that evaluates to an integer specifying the number of lines needed. is a required keyword.

num-expr
LINES

Notes
1. The NEED statement can prevent INFORMIX-4GL from splitting parts of the report that you want to keep together on a single page. 2. INFORMIX-4GL does not include the BOTTOM MARGIN value in the number of lines counted. 3. If INFORMIX-4GL triggers the NEED statement in printing a report, it prints both the PAGE TRAILER and the PAGE HEADER. 4. You cannot use this statement in PAGE HEADER or PAGE TRAILER control blocks.

Example
NEED 6 LINES

5-38

Report Writing

PAUSE

PAUSE
Overview
This statement causes output to the terminal to pause until the user presses RETURN.

Syntax
PAUSE [ "string" ]

Explanation
PAUSE

is a required keyword. is a quoted message that PAUSE displays. If you do not supply a message, PAUSE displays no message.

string

Notes
The PAUSE statement works only if the report goes to the screen. It has no effect if you include a REPORT TO clause in the OUTPUT section, or a TO clause in the START REPORT statement.

Example
The following example causes INFORMIX-4GL to pause while running the report.
AFTER GROUP OF item_num . . . SKIP TO TOP OF PAGE PAUSE "Press RETURN to continue"

Report Writing

5-39

PRINT

PRINT
Overview
This statement displays information, as specied in the OUTPUT section.

Syntax
PRINT [ exprlist ] [ ; ]

Explanation
PRINT

is a required keyword. is an optional list of one or more expressions, separated by commas. is an optional symbol that suppresses a RETURN at the end of the line.

exprlist ;

Notes
1. One PRINT statement displays its output on one line, no matter how many lines the statement occupies in the report specication, unless the exprlist includes the WORDWRAP function. 2. When a PRINT statement species WORDWRAP, it can also specify a temporary right margin. The character position of the current column becomes the temporary left margin, and the contents of the character string are then displayed on as many lines as necessary between these temporary margins. After the PRINT statement with WORDWRAP has executed, any explicit or default margins from the OUTPUT section are restored. 3. Unless you use the keyword CLIPPED or USING following an expression, INFORMIX-4GL displays variables with a width that depends on their data type, as shown in Figure 5-2.

5-40

Report Writing

PRINT

Data Type CHAR DATE DATETIME INTERVAL FLOAT SMALLINT INTEGER SMALLFLOAT DECIMAL SERIAL MONEY Figure 5-2

Default Size (in characters) declared size 10 depends on declared precision depends on declared precision (including sign) 14 (including sign and decimal point) 6 (including sign) 11 (including sign) 14 (including sign and decimal point) number of digits plus 2 (including sign and decimal point) 11 number of digits plus 3 (including sign, decimal point, and currency symbol) Default Display Widths

Examples
The following example is from a mailing label report:
FORMAT ON EVERY ROW PRINT fname, lname PRINT company PRINT address1 PRINT address2 PRINT city, ", " , state, 2 SPACES, zipcode SKIP 2 LINES

The following example is from a report that prints the customer list.
FIRST PAGE HEADER PRINT COLUMN 30, "CUSTOMER LIST" SKIP 2 LINES PRINT "Listings for the State of ", thisstate SKIP 2 LINES PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "LOCATION", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE PAGE HEADER PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "LOCATION", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE ON EVERY ROW PRINT customer_num USING "####", COLUMN 12, fname CLIPPED, 1 SPACE, lname CLIPPED, COLUMN 35, city CLIPPED, ", " , state, COLUMN 57, zipcode, COLUMN 65, phone

Report Writing

5-41

PRINT FILE

PRINT FILE
Overview
This statement displays the contents of a text le in a report.

Syntax
PRINT FILE "lename"

Explanation
PRINT FILE

are required keywords. is a required lename that can be a pathname. You must enclose lename in quotation ( " ) marks.

lename

Note
You can use the PRINT FILE statement to include the body of a form letter in a report that generates custom letters.

Example
PRINT FILE "/u/claire/occupant.let"

5-42

Report Writing

SKIP

SKIP
Overview
This statement skips lines in a report or skips to the top of the next page.

Syntax
SKIP { integer LINE[S] | TO TOP OF PAGE }

Explanation
SKIP

is a required keyword. is an integer specifying the number of lines to skip. is an optional keyword. You can use the keyword LINE in place of LINES if you like. are optional keywords.

integer
LINES TO TOP OF PAGE

Notes
1. You cannot use a SKIP LINES statement inside a CASE, FOR, or WHILE statement. 2. You cannot use a SKIP TO TOP OF PAGE statement in a FIRST PAGE HEADER, PAGE HEADER, or PAGE TRAILER control block.

Report Writing

5-43

Expressions and Built-in Functions

Examples
The following example is from a report that prints the customer list.
FIRST PAGE HEADER PRINT COLUMN 30, "CUSTOMER LIST" SKIP 2 LINES PRINT "Listings for the State of ", thisstate SKIP 2 LINES PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "LOCATION", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE PAGE HEADER PRINT "NUMBER", COLUMN 12, "NAME", COLUMN 35, "LOCATION", COLUMN 57, "ZIP", COLUMN 65, "PHONE" SKIP 1 LINE ON EVERY ROW PRINT customer_num USING "####", COLUMN 12, fname CLIPPED, 1 SPACE, lname CLIPPED, COLUMN 35, city CLIPPED, ", " , state, COLUMN 57, zipcode, COLUMN 65, phone

The next example is from a mailing label report.

FORMAT ON EVERY ROW IF (city IS NOT NULL) AND (state IS NOT NULL) THEN PRINT fname CLIPPED, 1 SPACE, lname PRINT company PRINT address1 IF (address2 IS NOT NULL) THEN PRINT address2 PRINT city CLIPPED, ", " , state, 2 SPACES, zipcode SKIP TO TOP OF PAGE END IF

Expressions and Built-in Functions

Expressions used within REPORT routines have the same syntax as expressions used elsewhere in INFORMIX-4GL. These expressions can include the built-in functions that are described in Chapter 2. You can also use the 4GL aggregate functions. In REPORT routines, these aggregates have effects that are slightly different from when they are used in a SELECT statement. The differences are described in the next pages.

5-44

Report Writing

Expressions and Built-in Functions

There are also built-in functions that you can use only in a REPORT routine. The following table lists all the functions that you can use in a REPORT routine. (The letter superscripts indicate where their descriptions appear in this manual.)
ASCIIa AVG()rs CLIPPEDa COLUMNa COUNT(*)rs CURRENTa DATEa DATE()a DAY()a EXTEND()a GROUPr LENGTH()a LINENOr MAX()rs MIN()rs MDY()a MONTH()a PAGENOr PERCENT(*)rs SPACESr SUM()rs TIMEa TODAYa UNITSa USINGa WEEKDAY()a WORDWRAPr YEAR()a

r rs

You can use these functions only within the FORMAT section of a REPORT routine. A description of these functions follows. You can use these functions only within the FORMAT section of a REPORT routine or in INSERT, SELECT, or UPDATE statements elsewhere. They are described both in the following pages and in Chapter 7. These functions are described in Chapter 2.

Report Writing

5-45

Aggregates

Aggregates
Overview
Aggregate functions can summarize information in a report.

Syntax
[ GROUP ] { COUNT ( * ) | PERCENT ( * ) | { SUM | AVG | MIN | MAX } ( expr1 ) } [ WHERE expr2 ]

Explanation
GROUP

is an optional keyword that causes the aggregate to reect information for a specic group only. You can only use this keyword in an AFTER GROUP OF control block. is a keyword. This keyword is always evaluated as the total number of rows qualied by the optional WHERE clause. is the keyword that evaluates COUNT as a percent of the total number of rows in the report. evaluates as the total of expr1 in the rows qualied by the optional WHERE clause. SUM ignores rows with NULL value for expr1; it returns NULL if all rows have a NULL value for expr1. evaluates as the average of expr1 in the rows qualied by the optional WHERE clause. AVG ignores rows with NULL value for expr1; it returns NULL if all rows have a NULL value for expr1. evaluates as the minimum of expr1 in the rows qualied by the optional WHERE clause. MIN ignores rows with NULL value for expr1; it returns NULL if all rows have a NULL value for expr1. evaluates as the maximum of expr1 in the rows qualied by the optional WHERE clause. MAX ignores rows with NULL value for expr1; it returns NULL if all rows have a NULL value for expr1. is the expression that SUM, AVG, MIN, or MAX evaluate. It is typically a numeric variable or a numeric expression that includes a numeric variable.

COUNT ( * ) PERCENT ( * ) SUM

AVG

MIN

MAX

expr1

5-46

Report Writing

Aggregates

WHERE

is an optional keyword. is a Boolean expression that qualies the aggregate.

expr2

Note
The WHERE clause allows you to select among the rows passed to the report. (See The SELECT Statement in Chapter 7 for the syntax of the WHERE clause. See also the section Boolean Expressions in Chapter 2.)

Examples
This fragment of a REPORT statement uses the AFTER GROUP OF control block and GROUP keyword to sum items within each order. The last PRINT statement calculates the total price of each order, then adds a shipping charge, and prints the result.
ON EVERY ROW PRINT snum USING "###", COLUMN 10, manu_code, COLUMN 18, description CLIPPED, COLUMN 38, quantity USING "###", COLUMN 43, unit_price USING "$$$$.&&", COLUMN 55, total_price USING "$$,$$$,$$$.&&" AFTER GROUP OF number SKIP 1 LINE PRINT 4 SPACES, "Shipping charges for the order: ", ship_charge USING "$$$$.&&" PRINT 4 SPACES, "Count of small orders: ", count(*) WHERE total_price < 200.00 USING "##,###" SKIP 1 LINE PRINT 5 SPACES, "Total amount for the order: ", ship_charge + GROUP SUM(total_price) USING "$$,$$$,$$$.&&"

Since no WHERE clause is specied, GROUP SUM combines the total_price of every item in the group comprising the order.

Report Writing

5-47

LINENO

LINENO
Overview
This expression has the value of the line number of the report line that INFORMIX-4GL is currently printing.

Syntax
LINENO

Explanation
LINENO

is a required keyword.

Note
INFORMIX-4GL computes the current line number by calculating the number of lines from the top of the page, including the TOP MARGIN.

Example
PRINT COLUMN 10, LINENO USING "Line <<<"

5-48

Report Writing

PAGENO

PAGENO
Overview
This expression has the value of the page number of the page that INFORMIX-4GL is currently printing.

Syntax
PAGENO

Explanation
PAGENO is a required keyword.

Note
You can use PAGENO in a PRINT statement in the PAGE HEADER or PAGE TRAILER control block to number the pages of a report. (You can also use PAGENO in other control blocks.)

Example
PAGE TRAILER PRINT COLUMN 28, PAGENO USING "page <<<<"

Report Writing

5-49

SPACES

SPACES
Overview
This function returns a string of spaces. It is identical to a quoted string of spaces.

Syntax
num-expr SPACE[S]

Explanation
num-expr is a number expression.
SPACES

is a required keyword. You can use the keyword SPACE in place of SPACES if you like.

Example
The following example is from a mailing label report.
FORMAT ON EVERY ROW PRINT fname, lname PRINT company PRINT address1 PRINT address2 PRINT city, ", " , state, 2 SPACES, zipcode SKIP 2 LINES

5-50

Report Writing

WORDWRAP

WORDWRAP
Overview
The WORDWRAP function automatically wraps successive segments of long character strings to the next line of a report. If the string is too long to t in the current line, lines are broken between words at temporary left and right margins.

Syntax
char-expr WORDWRAP [ RIGHT MARGIN col ]

Explanation
char-expr
WORDWRAP

is an expression whose value is a character string. is a keyword to display long character strings on multiple lines of a report. are optional keywords to specify a temporary right margin. is an integer expression, specifying the column number of the temporary right margin.

RIGHT MARGIN col

Notes
1. The char-expr can include printable ASCII characters, and the TAB (ASCII 9), NEWLINE (ASCII 10), and RETURN (ASCII 13). A line break is forced wherever char-expr contains a NEWLINE, a RETURN, or a NEWLINE/ RETURN pair. 2. If you specify WORDWRAP RIGHT MARGIN in a report, the value of col overrides the specied or default right margin, until all of char-expr has been included in the report. 3. If you do not specify RIGHT MARGIN, the specied or default right margin of the report remains in effect. 4. The left margin is the current printing column. The contents of char-expr are displayed on as many lines as necessary between the temporary left and right margins. 5. When displaying text with WORDWRAP, INFORMIX-4GL starts a new line when a word plus the following space will not t on the current line,
Report Writing 5-51

WORDWRAP

thereby assuring an even left margin when all words are separated by a single space. When a string of spaces will not t on a line, INFORMIX-4GL prints enough of the spaces to ll the line, starts a new line, and prints the rest of the spaces. INFORMIX-4GL expands a TAB down to enough spaces to reach the next TAB stop. When the next TAB stop is past the right margin, INFORMIX-4GL expands just to the right margin, starts a new line, and fetches the next word. 6. INFORMIX-4GL will maintain page discipline while printing data with the WORDWRAP utility; it will print page footers, page trailers, page numbers, and page headers.

Examples
The following PRINT statement species a left margin in column 10 and a temporary right margin in column 70 to display the character string that is stored in the variable called mynovel:
print column 10, mynovel WORDWRAP RIGHT MARGIN 70

If the data string is too long to t in the rst line, successive segments are displayed in successive lines, until the last character of the string is displayed. Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information

5-52

Report Writing

Chapter

4GL Function Library

Chapter Overview 3 The 4GL Library Functions ARG_VAL 4 ARR_COUNT 6 ARR_CURR 7 DOWNSHIFT 9 ERR_GET 10 ERR_PRINT 11 ERR_QUIT 12 ERRORLOG 13 INFIELD 14 LENGTH 16 NUM_ARGS 17 SCR_LINE 18 SET_COUNT 20 SHOWHELP 21 STARTLOG 23 UPSHIFT 25 3

6-2

4GL Function Library

Chapter Overview
This chapter describes the INFORMIX-4GL library functions. You can include any of these functions in your 4GL source code. The 4GL compiler recognizes the name of the library function and automatically includes the function in your nal program. See also the section Expressions and Built-in Functions near the end of Chapter 5 for a list of additional functions that you can include in 4GL programs.

The 4GL Library Functions

You cannot include a library function in an SQL statement. You must use the CALL statement to invoke a library function, unless its action returns a single value. The functions marked with an asterisk ( * ) in the following list can only be used in CALL statements. The functions listed without an asterisk can be used without CALL in 4GL expressions or in assignment statements.
Function arg_val arr_count arr_curr downshift err_get err_print err_quit errorlog ineld length num_args scr_line set_count showhelp startlog upshift Returned Value or Effect Command-line argument(s) Total lled rows of program array Number of the current row within program array Lowers case of uppercase letters in string argument Current 4GL error message Prints a 4GL error message on the Error line Prints a 4GL error message and exits Appends argument to the error log TRUE if argument is the name of the current eld Length in bytes of string argument Number of command-line arguments Number of the current row within screen array Sets number of rows of program array Displays the 4GL HELP Menu and a help message Opens an error log le Raises case of lowercase letters in string argument

* * *

* * *

The pages that follow describe these functions in alphabetical order.

ARG_VAL

ARG_VAL
Overview
The arg_val function returns an argument of the command line that executes your INFORMIX-4GL application program.

Syntax
arg_val ( expr )

Explanation
expr is an integer expression.

Notes
1. You can design your 4GL program to expect or allow arguments after the name of the program in the command line. Use the arg_val function to retrieve individual arguments during program execution. The num_args function can determine how many arguments followed the program name on the command line. The arg_val and num_args functions allow you to pass data to a compiled 4GL program from the command line that executes the program. 2. The function arg_val(n) returns the nth command-line argument as a CHAR variable. 3. The value of expr must be between 0 and the value returned by num_args, which is the number of command-line arguments. The value returned by arg_val(0) is the name of your 4GL application program.

Examples
Suppose that your 4GL program called myprog can accept one or more usernames as command-line arguments. Each of the following command lines includes four arguments: myprog.4ge joe bob sue les (C Compiler Version) fglgo myprog joe bob sue les (Rapid Development System)

6-4

4GL Function Library

ARG_VAL

In either case, statements in the following program fragment use the arg_val function to store in an array of CHAR variables all the names that the user entered as command-line arguments:
. . . DEFINE args ARRAY[8] OF CHAR(10), i SMALLINT . . . FOR i = 1 TO num_args() LET args[i] = arg_val(i) END FOR . . .

After the command-line arguments listed above, the num_args function returns the value 4. Executing the LET statements in the FOR loop assigns the following values to elements of the args array:
Variable args[1] args[2] args[3] args[4] Value joe bob sue les

Related Function
NUM_ARGS

4GL Function Library

6-5

ARR_COUNT

ARR_COUNT
Overview
The arr_count function returns the number of rows that are entered in a program array during or after an INPUT ARRAY statement.

Syntax
arr_count ( )

Notes
You can use arr_count to record the number of rows that are currently stored in a program array. The arr_count function returns an integer value.

Example
The following function uses the value returned by arr_count to set the upper limit of a FOR statement:
FUNCTION insert_items() DEFINE counter SMALLINT FOR counter = 1 TO arr_count() INSERT INTO items VALUES (p_items[counter].item_num, p_orders.order_num, p_items[counter].stock_num, p_items[counter].manu_code, p_items[counter].quantity, p_items[counter].total_price) END FOR END FUNCTION

Related Functions
ARR_CURR, SCR_LINE

6-6

4GL Function Library

ARR_CURR

ARR_CURR
Overview
The arr_curr function returns the number of the row within the program array that corresponds to the current screen array row, during or immediately after the INPUT ARRAY or DISPLAY ARRAY statement.

Syntax
arr_curr ( )

Notes
1. The current screen row is the row where the cursor is located at the beginning of a BEFORE ROW or AFTER ROW clause. 2. The arr_curr function returns an integer value. The rst row of both the program array and the screen array is numbered 1. 3. The library functions arr_curr and scr_line can return different values if the program array is larger than the screen array.

4GL Function Library

6-7

ARR_CURR

Example
The following program segment tests the user input and rejects it if the customer is not from California. (See also the denition of the scr_line function later in this chapter.)
DEFINE p_array ARRAY[90] OF RECORD fname CHAR(15), lname CHAR(15), state CHAR(2) END RECORD, pa_curr, sc_curr SMALLINT INPUT ARRAY p_array FROM scr_array.* AFTER FIELD state LET pa_curr = arr_curr() LET sc_curr = scr_line() IF upshift(p_array[pa_curr].state) != "CA" THEN ERROR "Customers must be from California" INITIALIZE p_array[pa_curr].* TO NULL CLEAR scr_array[sc_curr].* NEXT FIELD fname END IF END INPUT

Related Functions
ARR_COUNT, SCR_LINE

6-8

4GL Function Library

DOWNSHIFT

DOWNSHIFT
Overview
The downshift function returns a string value in which all uppercase characters in its argument are converted to lowercase.

Syntax
downshift ( str )

Explanation
str is a quoted string or a variable of type CHAR.

Notes
1. Non-alphabetic characters in str are not altered by downshift. 2. You can use the downshift function in an expression (when such usage is allowed), or you can assign the value returned by the function to a variable. 3. The maximum length of str is 512 characters. 4. See also the DOWNSHIFT eld attribute in Chapter 4.

Example
Suppose that the CHAR value GEAR_4 is stored in the program variable p_string. The following statement takes the value of the expression downshift(p_string), namely gear_4, and assigns it to another CHAR variable called d_str:
LET d_str = downshift(p_string)

Related Function
UPSHIFT

4GL Function Library

6-9

ERR_GET

ERR_GET
Overview
The err_get function returns a CHAR string that is the 4GL error message corresponding to its argument.

Syntax
err_get ( expr )

Explanation
expr is an integer expression.

Notes
1. The expr is usually the global status variable. 2. The err_get function is most useful when you are developing a program. The message that it returns is probably not helpful to the user of your application.

Example
The LET statement in this segment assigns the text of a 4GL error message to errtext, a CHAR variable:
IF status < 0 THEN LET errtext = err_get(status) END IF

Related Functions
ERR_PRINT, ERR_QUIT, STARTLOG

6-10

4GL Function Library

ERR_PRINT

ERR_PRINT
Overview
The err_print function displays on the Error line the INFORMIX-4GL error message that corresponds to its argument.

Syntax
CALL err_print ( expr )

Explanation
expr is an integer expression.

Notes
1. The expr is usually the global status variable. 2. The err_print function is most useful when you are developing a program. The message that it returns is probably not helpful to the user of your application.

Example
This program segment sends any error message to the Error line:
IF status < 0 THEN CALL err_print(status) END IF

Related Functions
ERR_GET, ERR_QUIT, STARTLOG

4GL Function Library

6-11

ERR_QUIT

ERR_QUIT
Overview
The err_quit function prints on the Error line the INFORMIX-4GL error message specied by its argument, and then terminates the program.

Syntax
CALL err_quit ( expr )

Explanation
CALL

is a required keyword. is an integer expression.

expr

Notes
1. The expr is usually the global status variable. 2. The err_quit function is most useful when you are developing a program. The message that it returns is probably not helpful to the user of your application.

Example
If an error occurs, these statements display the error message on the Error line, and then terminate program execution:
IF status < 0 THEN CALL err_quit(status) END IF

Related Functions
ERR_GET, ERR_PRINT, STARTLOG

6-12

4GL Function Library

ERRORLOG

ERRORLOG
Overview
The errorlog function writes its argument in the current error log le.

Syntax
CALL errorlog ( str )

Explanation
CALL

is a required keyword. is a string constant or a CHAR variable.

str

Notes
1. The error log le is created by the startlog function. 2. You can use the errorlog function to identify errors in programs that you are developing and to customize error handling.

Example
Here the errorlog function has a string constant argument:
CALL startlog("/usr/steve/error.log") ... FUNCTION start_menu() CALL errorlog("Entering start_menu function")

Related Function
STARTLOG

4GL Function Library

6-13

INFIELD

INFIELD
Overview
The ineld function tests whether its argument is the identier of the current screen eld.

Syntax
infield ( eld-name )

Explanation
eld-name is the name of a screen eld.

Notes
1. The ineld function is a Boolean function that returns the value true if eld-name is the name of the current screen eld. Otherwise ineld returns the value false. (The ATTRIBUTES Section in Chapter 4 describes how to assign a eld-name to a display eld of a screen form.) 2. You can use ineld during an INPUT or INPUT ARRAY statement to take eld-dependent actions. 3. Outside of an INPUT or INPUT ARRAY statement, ineld returns a true or false value, based on whether eld-name corresponds to the screen eld that was current when the user terminated the most recent INPUT or INPUT ARRAY statement. Be sure to specify the eld-name, not the eld tag. 4. If the current eld is a multiple-column eld, ineld returns true only if eld-name is the active name.

6-14

4GL Function Library

INFIELD

Example
The following INPUT statement uses ineld with showhelp to give elddependent help messages.
INPUT p_rec.* FROM sc_rec.* ON KEY(CONTROL-B) CASE WHEN infield(field1) CALL showhelp(101) WHEN infield(field2) CALL showhelp(102) WHEN infield(field3) CALL showhelp(103) ... END CASE END INPUT

Related Function
SCR_LINE

4GL Function Library

6-15

LENGTH

LENGTH
Overview
The length function returns the number of bytes in its string argument, after deleting all trailing spaces.

Syntax
length ( str )

Explanation
str is a string constant or a CHAR variable.

Note
In a SELECT statement, with str the name of a character column, this function returns the number of bytes in each CLIPPED value. (This is an exception to the rule that library functions cannot occur in SQL statements.)

Examples
These statements center a report title on an 80-column page:
LET title = "Invoice for ", fname CLIPPED, " ", lname CLIPPED LET offset = (80 - length(title))/2 PRINT COLUMN offset, title

The next statement retrieves the value in column1 and the length in bytes of the string in column2 (excluding trailing blanks).
SELECT column1, LENGTH(column2) FROM mytable

Note: INFORMIX-OnLine supports additional functionality. Refer to the INFORMIX-OnLine Programmers Manual for more information.

6-16

4GL Function Library

NUM_ARGS

NUM_ARGS
Overview
The num_args function returns the number of command-line arguments with which your INFORMIX-4GL program is run.

Syntax
num_args ( )

Note
The num_args function returns an integer, indicating the number of command-line arguments that followed the name of your program when the user invoked it. (You can use the arg_val library function to retrieve individual arguments.)

Example
Each of the following command lines includes three arguments: myprog.4ge kim sue joe fglgo myprog kim sue joe
(C Compiler Version) (Rapid Development System)

After either of these command lines, num_args sets 3 as the upper limit of i in the FOR statement of the program fragment that follows.
DEFINE args ARRAY[8] OF CHAR(10), i SMALLINT FOR i = 1 TO num_args() LET args[i] = arg_val(i) END FOR

Related Function
ARG_VAL

4GL Function Library

6-17

SCR_LINE

SCR_LINE
Overview
The scr_line function returns the number of the current screen row within its screen array during a DISPLAY ARRAY or INPUT ARRAY statement.

Syntax
scr_line ( )

Notes
1. The current screen row is the row where the cursor is located at the beginning of a BEFORE ROW or AFTER ROW clause. 2. The rst row of both the program array and of the screen array is numbered 1. 3. The library functions scr_line and arr_curr can return different values if the program array is larger than the screen array.

6-18

4GL Function Library

SCR_LINE

Example
The following program segment tests the user input and rejects it if the customer is not from Alaska. (See also the denition of the arr_curr library function earlier in this chapter.)
DEFINE p_array ARRAY[90] OF RECORD fname CHAR(15), lname CHAR(15), state CHAR(2) END RECORD, pa_curr, sc_curr SMALLINT INPUT ARRAY p_array FROM scr_array.* AFTER FIELD state LET pa_curr = arr_curr() LET sc_curr = scr_line() IF upshift(p_array[pa_curr].state) != "AK" THEN ERROR "Customers must be from Alaska" INITIALIZE p_array[pa_curr].* TO NULL CLEAR scr_array[sc_curr].* NEXT FIELD fname END IF END INPUT

Related Functions
ARR_COUNT, ARR_CURR

4GL Function Library

6-19

SET_COUNT

SET_COUNT
Overview
The set_count function tells INFORMIX-4GL the number of lled rows in a program array.

Syntax
CALL set_count ( expr )

Explanation
CALL

is a required keyword. is an integer expression.

expr

Note
Before you use an INPUT ARRAY WITHOUT DEFAULTS or a DISPLAY ARRAY statement, you must call the set_count function with an integer argument that species the total number of lled rows in the program array. This function supplies an initial value for the arr_count library function to return.

Example
CALL set_count(23) INPUT ARRAY p_array WITHOUT DEFAULTS FROM s_array.*

Related Functions
ARR_COUNT, ARR_CURR

6-20

4GL Function Library

SHOWHELP

SHOWHELP
Overview
The showhelp function displays a help screen. When the user clears the help screen, INFORMIX-4GL restores the previous screen.

Syntax
CALL showhelp ( expr )

Explanation
CALL

is a required keyword. is an integer expression.

expr

Notes
1. When called with an argument that is the number of a help message in the help le named in an OPTIONS statement, showhelp clears the screen, displays the help message, and presents the user with a menu of help options. 2. If the help message is too long to t on one screen, a Screen option of the HELP Menu allows the user to display the next part of the message. 3. When the user selects Resume from the HELP Menu, the help screen is cleared, and the previous screen is restored. 4. For information on setting up a help le, see the description of the mkmessage utility in Appendix E, or the section entitled Creating Help Messages in Chapter 8 of the INFORMIX-4GL User Guide.

4GL Function Library

6-21

SHOWHELP

Example
The following example uses ineld with showhelp to display eld-dependent help messages.
INPUT p_rec.* FROM sc_rec.* ON KEY(CONTROL-B) CASE WHEN infield(field1) CALL showhelp(101) WHEN infield(field2) CALL showhelp(102) WHEN infield(field3) CALL showhelp(103) ... END CASE END INPUT

Related Function
INFIELD

6-22

4GL Function Library

STARTLOG

STARTLOG
Overview
The startlog function opens an error log le.

Syntax
CALL startlog ( lename )

Explanation
CALL

is a required keyword. is a quoted string or a CHAR variable that evaluates to the name (or the pathname) of the error log le.

lename

Notes
1. If lename does not exist, startlog creates it. If the le exists, startlog opens it, and positions the le pointer so that subsequent error messages are appended to it. 2. If you do not want the error log le to reside in the current directory, you must specify a full pathname. 3. After you call the startlog function, a record of every subsequent error that occurs during the execution of your program is written to the error log le. 4. The error record consists of the date, time, source-module name and line number, error number, and error message. 5. You can write your own messages in the error log le by using the errorlog function.

4GL Function Library

6-23

STARTLOG

Example
In the following example, a CALL statement invokes the startlog library function, specifying the name of the error log le in a quoted string that includes a pathname and le extension.
... CALL startlog("/usr/steve/error.log") ... FUNCTION start_menu() CALL errorlog("Entering start_menu function") ...

Related Function
ERRORLOG

6-24

4GL Function Library

UPSHIFT

UPSHIFT
Overview
The upshift function returns a string in which all lowercase characters in its argument are converted to uppercase characters.

Syntax
upshift ( str )

Explanation
str is a quoted string or a variable of type CHAR.

Notes
1. Non-alphabetic characters in str are not altered. 2. You can use the upshift function in an expression (when such usage is allowed) or in a statement that assigns the value returned by the function to a program variable. 3. The maximum length of str is 512 characters. 4. See also the UPSHIFT eld attribute in Chapter 4.

Example
Here the CHAR variables u_str and str are equivalent, except that u_str substitutes uppercase letters for any lowercase letters in str.
LET u_str = upshift(str) DISPLAY u_str

Related Function
DOWNSHIFT

4GL Function Library

6-25

UPSHIFT

6-26

4GL Function Library

Chapter

INFORMIX-4GL Statement Syntax

Types of Statements 5 Statements Supported Only on INFORMIX-SE 6 Statements Supporting INFORMIX-OnLine Enhancements 7 INFORMIX-4GL Extensions to ANSI Syntax 7 SELECT Statement 8 DECLARE Statement 9 UPDATE Statement 9 GRANT Statement 9 CREATE TABLE Statement 10 CREATE VIEW Statement 10 Denition of Statements 11 ALTER INDEX 12 ALTER TABLE ( O ) 14 BEGIN WORK 18 CALL 19 CASE 21 CLEAR 23 CLOSE 25 CLOSE DATABASE 27 CLOSE FORM 28 CLOSE WINDOW 30 COMMIT WORK 31 CONSTRUCT 32 CONTINUE 38 CREATE AUDIT 39 CREATE DATABASE ( O ) CREATE INDEX 44 CREATE SYNONYM 47

7
41

CREATE TABLE ( O ) 49 CREATE VIEW 57 CURRENT WINDOW 60 DATABASE 62 DECLARE 64 DEFER 69 DEFINE 71 DELETE 73 DISPLAY 75 DISPLAY ARRAY 79 DISPLAY FORM 83 DROP AUDIT 85 DROP DATABASE 86 DROP INDEX 88 DROP SYNONYM 89 DROP TABLE 90 DROP VIEW 91 ERROR 92 EXECUTE 94 EXIT 96 FETCH 98 FINISH REPORT 101 FLUSH 102 FOR 104 FOREACH 106 FREE ( O ) 109 FUNCTION 110 GLOBALS 112 GOTO 114 GRANT 115 IF 118 INITIALIZE 120 INPUT 122 INPUT ARRAY 129 INSERT 138 LABEL 141 LET 142 LOAD 143 LOCK TABLE 146 MAIN 148 MENU 149 MESSAGE 154 OPEN 156
7-2 INFORMIX-4GL Statement Syntax

OPEN FORM 159 OPEN WINDOW 160 OPTIONS 165 OUTPUT TO REPORT 170 PREPARE 171 PROMPT 173 PUT 177 RECOVER TABLE 179 RENAME COLUMN 181 RENAME TABLE 182 REPORT 184 RETURN 186 REVOKE 187 ROLLBACK WORK 189 ROLLFORWARD DATABASE RUN 191 SCROLL 192 SELECT 193 SET EXPLAIN 194 SET LOCK MODE ( O ) 197 SLEEP 199 START DATABASE 200 START REPORT 202 UNLOAD 203 UNLOCK TABLE 205 UPDATE 206 UPDATE STATISTICS 210 VALIDATE 211 WHENEVER 213 WHILE 216 The SELECT Statement 218 SELECT Clause 222 INTO Clause 224 FROM Clause 226 WHERE Clause 228 Comparison Condition Join Conditions 234 Subquery 237 GROUP BY Clause 240 HAVING Clause 242 ORDER BY Clause 243 INTO TEMP Clause 245 UNION Operator 246

190

228

INFORMIX-4GL Statement Syntax

7-3

Functions in SQL Statements 248 Aggregate Functions 249 LENGTH( ) 251 DATE( ) 252 DAY( ) 253 MDY( ) 254 MONTH( ) 255 WEEKDAY( ) 256 YEAR( ) 257 CURRENT 258 EXTEND( ) 260

7-4

INFORMIX-4GL Statement Syntax

Types of Statements
Twelve types of INFORMIX-4GL statements are available:

Program Organization Statements

FUNCTION MAIN REPORT

Variable Denition Statements

DEFINE GLOBALS

Assignment Statements
INITIALIZE LET

Program Flow Statements

CALL CASE CONTINUE DEFER EXIT FOR FOREACH GOTO IF LABEL RETURN RUN SLEEP WHENEVER WHILE

Screen Interaction Statements

CLEAR CLOSE FORM CLOSE WINDOW CONSTRUCT CURRENT WINDOW DISPLAY DISPLAY ARRAY DISPLAY FORM ERROR INPUT INPUT ARRAY MENU MESSAGE OPEN FORM OPEN WINDOW OPTIONS PROMPT SCROLL

Report Generation Statements

FINISH REPORT OUTPUT TO REPORT START REPORT

INFORMIX-4GL Statement Syntax

7-5

Statements Supported Only on INFORMIX-SE

Data Denition Statements

ALTER INDEX ALTER TABLE CLOSE DATABASE CREATE DATABASE CREATE INDEX CREATE SYNONYM CREATE TABLE CREATE VIEW DATABASE DROP DATABASE DROP INDEX DROP SYNONYM DROP TABLE DROP VIEW RENAME COLUMN RENAME TABLE SET EXPLAIN UPDATE STATISTICS

Data Manipulation Statements

DELETE INSERT LOAD SELECT UNLOAD UPDATE

Cursor Manipulation Statements

CLOSE DECLARE FETCH FLUSH OPEN PUT SET EXPLAIN

Dynamic Management Statements

EXECUTE FREE PREPARE

Data Access Statements

GRANT LOCK TABLE REVOKE SET LOCK MODE UNLOCK TABLE

Data Integrity Statements

BEGIN WORK COMMIT WORK CREATE AUDIT DROP AUDIT RECOVER TABLE ROLLBACK WORK ROLLFORWARD DATABASE START DATABASE VALIDATE

Statements Supported Only on INFORMIX-SE

The following SQL statements are supported only on INFORMIX-SE. They cannot be used in INFORMIX-OnLine applications.
CREATE AUDIT DROP AUDIT RECOVER TABLE ROLLFORWARD DATABASE START DATABASE 7-6 INFORMIX-4GL Statement Syntax

Statements Supporting INFORMIX-OnLine Enhancements

Statements Supporting INFORMIX-OnLine Enhancements

The INFORMIX-OnLine database engine recognizes extensions to several SQL statements. Refer to the INFORMIX-OnLine Programmers Manual for details of the additional functionality available with INFORMIX-OnLine.
INFORMIX-4GL statements that support INFORMIX-OnLine enhancements

are listed here. They are identied in the following descriptions with an ( O ) after the name of the statement. Do not include the (O) when you type the statement.
ALTER TABLE ( O ) CREATE DATABASE ( O ) CREATE TABLE ( O ) FREE ( O ) SET LOCK MODE ( O )

INFORMIX-4GL Extensions to ANSI Syntax

Regardless of whether or not your database is MODE ANSI, you can check the SQL statements in your 4GL programs for ANSI compatibility. To check your programs at run time, you can set the DBANSIWARN environment variable. To check your programs at compile time, you can set the DBANSIWARN environment variable or use the -ansi ag when you compile your 4GL sourcecode les at the system prompt. Examples:
c4gl -ansi le.4gl -o program.4ge fglpc -ansi le.4gl (C Compiler Version)

(Rapid Development System)

When you compile with the -ansi ag or with the DBANSIWARN environment variable set, SQL statements that include Informix extensions to ANSI syntax cause warning messages to be written to the .err le. (See Appendix C for more information about DBANSIWARN.) Note: You cannot use the -ansi ag with i4gl or r4gl. When you run a compiled program after you have set DBANSIWARN, any extension to ANSI syntax in an SQL statement causes the characters SQLAWARN[1] and SQLAWARN[6] to be set to W.

INFORMIX-4GL Statement Syntax

7-7

INFORMIX-4GL Extensions to ANSI Syntax

The following SQL statements generate warnings when Informix extension checking is initiated:
ALTER INDEX ALTER TABLE BEGIN WORK CLOSE DATABASE CREATE AUDIT CREATE DATABASE CREATE INDEX CREATE SYNONYM CREATE TABLE CREATE VIEW DATABASE DROP AUDIT DROP DATABASE DROP INDEX DROP SYNONYM DROP TABLE DROP VIEW FLUSH FREE GRANT LOAD LOCK TABLE PUT RECOVER TABLE RENAME COLUMN RENAME TABLE REVOKE ROLLFORWARD DATABASE SET EXPLAIN SET LOCK MODE START DATABASE UNLOAD UNLOCK TABLE UPDATE STATISTICS

Note: The BEGIN WORK, LOAD, and UNLOAD statements generate warnings at compile time only. The next section lists keywords or features of INFORMIX-4GL that are extensions to ANSI standard syntax. A warning is generated if you include these keywords or features in an SQL statement, and then initiate Informix extension checking with the -ansi ag or with the DBANSIWARN environment variable.

SELECT Statement
The following keywords or features are Informix extensions to the SELECT statement:

Column labels Column subscripts Numbers as position indicators (for example, in a GROUP BY clause) INTO TEMP clause MATCHES keyword OUTER keyword UNIQUE keyword UNITS keyword

7-8

INFORMIX-4GL Statement Syntax

INFORMIX-4GL Extensions to ANSI Syntax

The following functions: CURRENT DATE( ) DAY( ) EXTEND( ) LENGTH( ) MDY( ) MONTH( ) TODAY WEEKDAY( ) YEAR( )
DECLARE Statement
The following keywords are Informix extensions to the DECLARE statement:

INSERT SCROLL WITH HOLD FOR UPDATE clause

UPDATE Statement
Specifying multiple columns in an UPDATE statement is an extension to the ANSI standard.

GRANT Statement
The following keywords are extensions to the GRANT statement:

AS CONNECT DBA RESOURCE

Use of the GRANT statement in INFORMIX-4GL always generates a warning when Informix extension checking is initiated. The ANSI standard requires that the GRANT statement be issued within the CREATE SCHEMA

INFORMIX-4GL Statement Syntax

7-9

INFORMIX-4GL Extensions to ANSI Syntax

AUTHORIZATION statement. For more information about the CREATE SCHEMA AUTHORIZATION statement, refer to the INFORMIX-SQL Reference

Manual.

CREATE TABLE Statement

The following features and keywords are Informix extensions to the CREATE
TABLE statement:

DISTINCT keyword IN keyword UNIQUE CONSTRAINT keywords TEMP keyword The following data types: DATE MONEY SERIAL SMALLFLOAT DATETIME INTERVAL
Use of the CREATE TABLE statement in INFORMIX-4GL always generates a warning when Informix extension checking is initiated. The ANSI standard requires that the CREATE TABLE statement be issued within the CREATE SCHEMA AUTHORIZATION statement. For more information about the CREATE SCHEMA AUTHORIZATION statement, refer to the INFORMIX-SQL Reference Manual.

CREATE VIEW Statement

Use of the CREATE VIEW statement in INFORMIX-4GL always generates a warning when Informix extension checking is initiated. The ANSI standard requires that the CREATE VIEW statement be issued within the CREATE SCHEMA AUTHORIZATION statement. For more information about the CREATE SCHEMA AUTHORIZATION statement, refer to the INFORMIX-SQL Reference Manual. Note: INFORMIX-OnLine supports additional keywords that are extensions. See the INFORMIX-OnLine Programmers Manual for more information.

7-10

INFORMIX-4GL Statement Syntax

Denition of Statements

Denition of Statements
The following section describes the INFORMIX-4GL statements. The statements appear in alphabetical order. (See also Chapter 5, which describes additional statements that can only appear in the FORMAT section of a REPORT routine, such as NEED, PAUSE, PRINT, PRINT FILE, and SKIP.)

INFORMIX-4GL Statement Syntax

7-11

ALTER INDEX

ALTER INDEX
Overview
Use the ALTER INDEX statement to cluster a table in the order of an existing index, or to release an index from the clustering attribute.

Syntax
ALTER INDEX index-name TO [ NOT ] CLUSTER

Explanation
ALTER INDEX

are required keywords. is the identier of an existing index. is a required keyword. is an optional keyword. is a required keyword.

index-name
TO NOT CLUSTER

Notes
1. The TO CLUSTER option causes INFORMIX-4GL to reorder the rows in the physical table to agree with the order of index-name. Reordering causes the entire le to be rewritten. This process may take a long time and requires sufcient disk space to maintain two copies of the table. After all rows have been copied to the reordered table, the original version of the table is automatically deleted, releasing the additional disk space. 2. Since there can be only one clustered index per table, you must use the NOT option to release the cluster attribute from one index before assigning it to another. The NOT option does not affect the physical table; it merely drops the cluster attribute on index-name from the system catalogs. 3. When INFORMIX-4GL executes ALTER INDEX with the TO CLUSTER option, it locks the table in EXCLUSIVE MODE. If some other process is using the table to which index-name belongs, INFORMIX-4GL cannot execute ALTER INDEX with the TO CLUSTER option and returns an error. 4. You cannot use a ROLLBACK statement to undo the effect of the ALTER INDEX statement.

7-12

INFORMIX-4GL Statement Syntax

ALTER INDEX

5. As rows are added and deleted, you can expect the benet of an earlier clustering to disappear. You can recluster the table by issuing another ALTER INDEX TO CLUSTER statement on the clustered index. 6. You do not need to drop a cluster index before issuing another ALTER INDEX TO CLUSTER statement on a currently clustered index.

Example
The following example creates two indexes on the orders table and clusters the physical table in ascending order on the customer_num column. Later, the example clusters the physical table in ascending order on the order_num column.
CREATE UNIQUE INDEX ix_ord ON orders (order_num) CREATE CLUSTER INDEX ix_cust ON orders (customer_num) ... ALTER INDEX ix_cust TO NOT CLUSTER ALTER INDEX ix_ord TO CLUSTER

Related Statement
CREATE INDEX

INFORMIX-4GL Statement Syntax

7-13

ALTER TABLE ( O )

ALTER TABLE ( O )
Overview
Use the ALTER TABLE statement to add a column to a table, delete a column from a table, modify the data type of a column, add a UNIQUE CONSTRAINT to a column or a composite list of columns, or drop a UNIQUE CONSTRAINT associated with a column or composite list of columns.

Syntax
ALTER TABLE table-name { ADD ( newcol-name newcol-type [NOT NULL] [ UNIQUE [ CONSTRAINT constr-name ] ] [ , . . . ] ) [ BEFORE oldcol-name ] | DROP ( oldcol-name [ , . . . ] ) | MODIFY ( oldcol-name newcol-type [ NOT NULL ] [ , . . . ] ) | ADD CONSTRAINT UNIQUE ( oldcol-name [ , . . . ] ) [ CONSTRAINT constr-name ] | DROP CONSTRAINT ( constr-name [ , . . . ] ) } [ , . . . ]

Explanation
ALTER TABLE

are required keywords. is the name of an existing table. is a keyword you use to add a column. is the name of the column you want to add. is either the data type of the column you are adding or the data type of the column you are modifying. are optional keywords. is a keyword specifying that the column or composite column list accepts only unique values. is a keyword you use to indicate that constr-name is assigned in the statement. is the name of the constraint. is an optional keyword you use to indicate where you want newcol-name placed in the list of columns. The default is at the end of the list of columns. is the name of an existing column. is a keyword you use to drop a column.

table-name
ADD

newcol-name newcol-type
NOT NULL UNIQUE CONSTRAINT

constr-name
BEFORE

oldcol-name
DROP 7-14 INFORMIX-4GL Statement Syntax

ALTER TABLE ( O )

MODIFY

is a keyword you use to change the data type of an existing column. are keywords you use to place a constraint on a column or composite column list. are keywords you use to drop a UNIQUE CONSTRAINT on a table column.

ADD CONSTRAINT DROP CONSTRAINT

Notes
1. In a MODE ANSI database, the name of a table is qualied by the owner of the table (owner. table-name). You must specify owner when you refer to a table owned by another user. The use of the prex owner. is optional in a non-MODE ANSI database. INFORMIX-4GL does check the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 for more information. 2. You can use one or more of the ADD, DROP, MODIFY, ADD CONSTRAINT, or DROP CONSTRAINT clauses, and you can place them in any order. Use a comma ( , ) to separate clauses. The actions are performed in the order specied. If any of the actions fail, the entire operation is canceled. 3. You cannot add a SERIAL column to a table. You must create a SERIAL column with the CREATE TABLE statement. You cannot add it with the ALTER TABLE statement. 4. You can modify an existing column that formerly permitted NULLs to be NOT NULL, provided that it does not already contain any NULL values. Specify MODIFY with the same oldcol-name and data type and the NOT NULL keywords. 5. You can modify an existing column that did not permit NULLs to permit NULLs. Specify MODIFY with the oldcol-name and the existing data type and omit NOT NULL. 6. When you add a new column to an existing table, it is lled with NULL values. Therefore, you cannot use the NOT NULL option or specify a UNIQUE CONSTRAINT when you add a column unless the table contains no data. 7. If you change the data type of an existing column, all data are converted to the new data type, including number to character and character to number (if the characters represent numbers). When there is a UNIQUE CONSTRAINT, however, conversion takes place only if it does not violate the constraint. If a data conversion would result in duplicate values (by changing FLOAT to SMALLFLOAT, for example, or
INFORMIX-4GL Statement Syntax 7-15

ALTER TABLE ( O )

by truncating CHAR values), then the ALTER TABLE command fails. You will receive error 212 (Cannot add index) and ISAM error 100 (There is already a record with the same value in a unique index). 8. When you drop a column that is part of a multiple-column constraint, you automatically drop the corresponding UNIQUE CONSTRAINT. 9. You can use ALTER TABLE with the ADD and CONSTRAINT keywords to specify a UNIQUE CONSTRAINT on a new or existing column, or on a composite list of columns. The following rules apply when adding a UNIQUE CONSTRAINT:

The columns can contain only unique values. A UNIQUE CONSTRAINT cannot already apply to the columns. An ascending index cannot already apply to the columns. A composite list can include no more than eight column names. An existing UNIQUE CONSTRAINT cannot have the same name.

10. To drop an existing constraint, specify DROP CONSTRAINT and the name of the constraint. If no constr-name name was specied when the constraint was created, the system generated the name. You can query the sysconstraints system catalog for the names (including the owner) of constraints. 11. If you own the table or have alter permission on the table, you can create a constraint on the table and specify yourself as the owner. If you have DBA permission, you can create constraints for other users. 12. You must own table-name, have DBA privilege, or be granted ALTER permission to use ALTER TABLE. 13. Altering a table on which a view depends may invalidate the view. 14. You cannot use a ROLLBACK WORK statement to undo an ALTER TABLE statement. 15. The keyword DISTINCT is a synonym for UNIQUE.

7-16

INFORMIX-4GL Statement Syntax

ALTER TABLE ( O )

Examples
ALTER TABLE items ADD (item_weight DECIMAL(6,2) BEFORE total_price) ALTER TABLE items DROP (total_price) ALTER TABLE items MODIFY (manu_code CHAR(4)) ALTER TABLE manufact ADD CONSTRAINT UNIQUE (manu_name) CONSTRAINT con_name ALTER TABLE manufact DROP CONSTRAINT (con_name)

Since they refer to the same table, you can combine the rst two examples into a single statement:
ALTER TABLE items ADD (item_weight DECIMAL(6,2) BEFORE total_price), DROP (total_price)

Related Statements
CREATE TABLE, CREATE INDEX, RENAME COLUMN, RENAME TABLE

INFORMIX-4GL Statement Syntax

7-17

BEGIN WORK

BEGIN WORK
Overview
Use the BEGIN WORK statement to start a transaction (a sequence of database operations that are terminated by the COMMIT WORK or ROLLBACK WORK statement) in a non-MODE ANSI database. See the section Transactions in Chapter 3 for a description of transactions.

Syntax
BEGIN WORK

Explanation
BEGIN WORK

are keywords to start a transaction.

Notes
1. Each row affected by an UPDATE, DELETE, or INSERT statement during a transaction is locked and remains locked throughout the transaction. A transaction that contains a large number of such statements, or that contains statements affecting a large number of rows, may exceed the limits placed by your operating system on the maximum number of simultaneous locks. If you encounter this error, you may need to lock the entire table immediately after beginning the transaction. See the section Locking in Chapter 3 for a more detailed description of table-level and rowlevel locking in INFORMIX-4GL. 2. Do not use the BEGIN WORK statement with a database CREATEd or STARTed as MODE ANSI. In a program that accesses a MODE ANSI database, the BEGIN WORK statement generates a run-time error unless it appears immediately after one of the following statements:
CREATE DATABASE DATABASE START DATABASE COMMIT WORK ROLLBACK WORK

3. See the Transactions section in Chapter 3 for a full description of transactions.

Related Statements
COMMIT WORK, ROLLBACK WORK

7-18

INFORMIX-4GL Statement Syntax

CALL

CALL
Overview
Use the CALL statement to invoke a function.

Syntax
CALL function ( [ argument-list ] ) [ RETURNING variable-list ]

Explanation
CALL

is a required keyword. is the name of a function. is a list of zero or more expressions, separated by commas and enclosed in parentheses, that are passed to the function. The parentheses are required, even if there are no arguments. is an optional keyword to specify variables that the function will return to the calling routine. is a list of one or more program variables, separated by commas.

function argument-list

RETURNING

variable-list

Notes
1. You can use the CALL statement to call INFORMIX-4GL functions and C language functions. See C Functions in Chapter 2 for the rules on using such functions in INFORMIX-4GL programs. 2. The arguments specied in argument-list will be passed by value. 3. You can dene INFORMIX-4GL functions in the same source le as the MAIN program block, or you can compile them separately and link them later to the MAIN program block.

Example
CALL statistics(rec.*) RETURNING mean, std_dev

INFORMIX-4GL Statement Syntax

7-19

CALL

Related Statements
DEFINE, FUNCTION

7-20

INFORMIX-4GL Statement Syntax

CASE

CASE
Overview
Use the CASE statement to select a sequence of statements, depending on the current value of an expression.

Syntax
CASE [ ( expr ) ] WHEN { expr | Boolean-expr } statement ... [ EXIT CASE ] ... WHEN { expr | Boolean-expr } statement ... [ EXIT CASE ] ... ... [ OTHERWISE ] statement ... [ EXIT CASE ] ... END CASE

Explanation
CASE

is a required keyword. is an expression that returns an INTEGER, SMALLINT, DECIMAL, or CHAR(1) value. is a required keyword. is an expression that is either TRUE or FALSE. is an INFORMIX-4GL statement. is an optional statement that causes program control to pass to the statement following the END CASE keywords. is an optional keyword introducing a sequence of statements to be executed if none of the WHEN clauses is executed. are required keywords that terminate the CASE statement.

expr
WHEN

Boolean-expr statement
EXIT CASE OTHERWISE END CASE

INFORMIX-4GL Statement Syntax

7-21

CASE

Notes
1. 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. 3. If the optional parenthesized expression following the CASE keyword is missing, you must follow the WHEN keyword with a Boolean expression. If there is an expression following the CASE keyword, you must follow the WHEN keyword with an expression that evaluates to the same data type. 4. There is an implied EXIT CASE statement at the end of each sequence of statements following a WHEN clause. Program control will pass to the sequence of statements following the END CASE statement.

Example
LABEL question: ... CASE WHEN answer MATCHES "[Yy]" CALL process() WHEN answer MATCHES "[Nn]" CALL abort() OTHERWISE CALL retry() END CASE

Related Statements
IF, EXIT

7-22

INFORMIX-4GL Statement Syntax

CLEAR

CLEAR
Overview
Use the CLEAR statement to clear the whole screen, a window, all elds in a screen form, or a set of elds.

Syntax
CLEAR { SCREEN | WINDOW window-name | FORM | eld-list }

Explanation
CLEAR SCREEN WINDOW

is a required keyword. is the keyword to clear the whole screen. is the keyword to clear a window. is the name of the window that you want to clear, or the keyword SCREEN. is the keyword to clear the values in all screen elds of a form. is a list of one or more names of elds to be cleared.

window-name
FORM

eld-list

Notes
1. The CLEAR statement does not change the value of any variable. It simply clears the display from the region indicated. 2. The CLEAR SCREEN statement makes the screen the current window and clears it. 3. The CLEAR WINDOW statement clears the specied window, retaining any border. (The specied window need not be the current window. This option does not affect which window is the current window.) 4. If you specify SCREEN as the window-name in a CLEAR WINDOW statement, INFORMIX-4GL clears the screen, except for the area occupied by any open windows. 5. CLEAR FORM and CLEAR eld-list apply to the form in the current window.

INFORMIX-4GL Statement Syntax

7-23

CLEAR

Examples
CLEAR fname, lname, address1, city, state, zipcode CLEAR FORM CLEAR SCREEN CLEAR WINDOW win1 CLEAR WINDOW SCREEN

7-24

INFORMIX-4GL Statement Syntax

CLOSE

CLOSE
Overview
Use the CLOSE statement when you no longer need to refer to the active set of a SELECT cursor, or when you want to ush the insert buffer and close an INSERT cursor.

Syntax
CLOSE cursor-name

Explanation
CLOSE

is a required keyword. is the name of a cursor that has been DECLAREd for a SELECT or INSERT statement.

cursor-name

Notes
1. If cursor-name is associated with a SELECT statement, the CLOSE statement puts the cursor in a closed state and leaves the active set undened. 2. After you CLOSE a SELECT cursor, you cannot execute a FETCH statement until you reopen the cursor. 3. If cursor-name is associated with an INSERT statement, the CLOSE statement ushes any rows in the buffer into the database (writes to disk) and closes the cursor. 4. After you CLOSE an INSERT cursor, you cannot execute a PUT or FLUSH statement until after you use an OPEN command to reopen the cursor. 5. The global variables status (whose value is taken from the SQLCA.SQLCODE ) and SQLCA. SQLERRD [3] indicate the result of each FLUSH and CLOSE statement for an INSERT cursor. If INFORMIX-4GL successfully inserts the buffered rows into the database, it sets status to zero, and SQLCA. SQLERRD [3] to the number of rows that were inserted into the database. If INFORMIX-4GL encounters an error while inserting the buffered rows into the database, it sets status to a negative number (specically, the number of the error message) and sets variable SQLCA. SQLERRD [3] to the number of rows successfully inserted into the database. Any buffered
INFORMIX-4GL Statement Syntax 7-25

CLOSE

rows following the last successfully inserted row are discarded. In this case, the cursor remains open. 6. Although the COMMIT WORK and ROLLBACK WORK statements CLOSE all open cursors (except cursors declared WITH HOLD ), do not use them for this purpose. You should explicitly CLOSE each INSERT cursor before committing the work, so that you can verify that the insertion was successful. 7. INFORMIX-4GL does not provide a global variable containing the total number of rows successfully inserted into the database with an INSERT cursor. If you want to know the total number of inserts performed, you must set a counter in your program and increment it upon each PUT statement. 8. If your database is not MODE ANSI but has transactions, you must issue the CLOSE statement within a transaction.

Examples
CLOSE query_cursor CLOSE icurs

Related Statements
DECLARE, FETCH, FLUSH, OPEN, PUT

7-26

INFORMIX-4GL Statement Syntax

CLOSE DATABASE

CLOSE DATABASE
Overview
Use the CLOSE DATABASE statement to close the current database.

Syntax
CLOSE DATABASE

Explanation
CLOSE DATABASE

are required keywords.

Notes
1. Following the CLOSE DATABASE statement, the only legal SQL statements are CREATE DATABASE, DATABASE, DROP DATABASE, ROLLFORWARD DATABASE, and START DATABASE. 2. Issue the CLOSE DATABASE statement before you DROP the current database. 3. The CLOSE DATABASE statement cannot appear in a multi-statement PREPARE.

Example
CLOSE DATABASE

Related Statements
CREATE DATABASE, DROP DATABASE, ROLLFORWARD DATABASE, START DATABASE

INFORMIX-4GL Statement Syntax

7-27

CLOSE FORM

CLOSE FORM
Overview
Use the CLOSE FORM statement to release the memory required for a screen form.

Syntax
CLOSE FORM form-name

Explanation
CLOSE FORM

are required keywords. is an INFORMIX-4GL identier that you assigned to a screen form in an OPEN FORM statement.

form-name

Notes
1. After you execute the CLOSE FORM statement, form-name is no longer associated with a screen form. Executing a subsequent DISPLAY FORM statement will give an error message. 2. If you execute a new OPEN FORM statement with the same form-name, INFORMIX-4GL will close the existing form before opening the new one. 3. When you execute the OPEN FORM statement, the compiled form is loaded into memory, where it remains until you execute a CLOSE FORM statement for that form. If you have displayed another form and wish to regain the memory allocated to the rst form, you can execute CLOSE FORM on the old form. 4. The CLOSE FORM statement affects memory use only and does not affect the logic of the program. Since allocating memory and reading a form from the disk takes time, you should leave forms open that you use repeatedly. 5. The CLOSE WINDOW statement closes any open form in the specied window, releasing the memory allocated to that form.

Example
CLOSE FORM order_entry 7-28 INFORMIX-4GL Statement Syntax

CLOSE FORM

Related Statements
CLOSE WINDOW, DISPLAY FORM, FREE, OPEN FORM

INFORMIX-4GL Statement Syntax

7-29

CLOSE WINDOW

CLOSE WINDOW
Overview
Use the CLOSE WINDOW statement to close a window.

Syntax
CLOSE WINDOW window-name

Explanation
CLOSE WINDOW

are required keywords. is the name of the window to be closed.

window-name

Notes
1. When you close a window, INFORMIX-4GL frees all resources used by the window, including forms, and restores the underlying display. 2. When you close the current window, the next window on the stack becomes the current window. When you close any other window, INFORMIX-4GL simply removes the window from the stack, leaving the current window unchanged. In both cases, INFORMIX-4GL restores the underlying display. 3. If you close a window that is currently being used for input, INFORMIX-4GL generates a run-time error. For example, closing the current window in the middle of a DISPLAY ARRAY, INPUT, INPUT ARRAY, or MENU statement produes a run-time error. 4. You cannot issue a CLOSE WINDOW screen command.

Example
CLOSE WINDOW win 1

Related Statements
CLEAR WINDOW, CURRENT WINDOW, OPEN WINDOW, OPTIONS

7-30

INFORMIX-4GL Statement Syntax

COMMIT WORK

COMMIT WORK
Overview
Use the COMMIT WORK statement to commit all modications made to the database during a transaction.

Syntax
COMMIT WORK

Explanation
COMMIT WORK

are required keywords.

Notes
1. Use the COMMIT WORK statement when you are satised with all changes made during the transaction to the database. Use the ROLLBACK WORK statement if you do not want to commit modications made during the transaction to the database. 2. The COMMIT WORK statement closes all open cursors, except cursors declared WITH HOLD. Do not use the COMMIT WORK statement within a FOREACH loop. 3. The COMMIT WORK statement releases all row and table locks. 4. See the section Transactions in Chapter 3 for details of how the the COMMIT WORK statement works.

Related Statements
BEGIN WORK, ROLLBACK WORK

INFORMIX-4GL Statement Syntax

7-31

CONSTRUCT

CONSTRUCT
Overview
Use the CONSTRUCT statement to create a CHAR variable that contains the Boolean expression constructed from a screen-generated query by example. The resulting CHAR variable contains conditions for the WHERE clause of a SELECT statement, corresponding to user-specied selection criteria.

Syntax
CONSTRUCT { BY NAME char-variable ON column-list | char-variable ON column-list FROM { eld-list | screen-record [ [ n ] ].* } [ , . . . ] } [ ATTRIBUTE ( attribute-list) ]

Explanation
CONSTRUCT BY NAME

is a required keyword. are keywords instructing INFORMIX-4GL to match names of database columns to screen eld names. is an identier of a CHAR type program variable (to contain the selection criteria). is a required keyword to specify database columns. is a list of one or more database column names, separated by commas. You can use the syntax table.*. is a keyword to specify screen elds for user entry of search values, and for display of query results. is a list of one or more screen eld names. is the identier of a collection of eld names dened in a form specication as a screen record. is an integer or integer variable, enclosed in brackets, to specify the row in a screen array in which the CONSTRUCT takes place. is a keyword to specify screen display attributes. is a list (in parentheses) of one or more screen display attributes, separated by commas.

char-variable
ON

column-list
FROM

eld-list screen-record [n]

ATTRIBUTE

(attribute-list)

7-32

INFORMIX-4GL Statement Syntax

CONSTRUCT

Notes
1. The CONSTRUCT statement allows the user to enter query-by-example search parameters in a screen form, with this syntax:
Symbol = > < >= <= <> : .. * ? | Name equal to greater than less than greater than or equal to less than or equal to not equal to range range wildcard for any string single-character wildcard or Data Types all all all all all all all DATETIME and INTERVAL CHAR CHAR all Pattern =x >x <x >=x <=x <>x x:y x..y *x, x*, *x* ?x, x?, ?x?, x?? a|b...

Explanation of Symbols

The equal sign ( = ) is the default query symbol for non-character columns, and for character columns in which the user enters a search value that does not contain wildcards: char-column = "value" If the user enters a character value that contains a wildcard character (either * or ? ), then MATCHES is the default query symbol: char-column MATCHES "value"

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

The x means any value of the appropriate data type for the search eld.
Enter the value immediately after any one of the rst six query symbols in the preceding table. Do not leave a space between the query symbol and the value.

The symbols >, <, > =, and < = imply an ordering of the data in the column. For CHAR data, greater than means later in the ASCII collating

INFORMIX-4GL Statement Syntax

7-33

CONSTRUCT

sequence (where a < A < 1 ), as listed in Appendix H. For DATE and DATETIME data, greater than means after.

Colon in x : y searches for all values between x and y, inclusive. Here

value y must be larger than x. The search criterion 1 : 10 would nd all rows with a value in that column from 1 through 10.

Substitute two periods ( . . ) for the colon in DATETIME and INTERVAL

ranges to avoid ambiguity with the eld separator in hh:mi:ss values.

Asterisk ( * ) is the string wildcard, representing zero or more characters. An *ts* search value in the eld corresponding to the lname column of the customer table would nd two names, Watson and Albertson. An S* search value in the same eld would nd Sadler and Sipes. An *er search value would nd the four names Sadler, Miller, Jaeger, and Baxter.

The question mark ( ? ) is the single-character wildcard. The user can

use the question mark to nd values that match a pattern where the number of characters is xed. For example, the user can enter Eriks?n to search for names like Erikson and Eriksen. Similarly, the user can enter New??n to search for names like Newton, Newman, and Newson.

The symbo| between values a and b means the logical OR. In the eld
corresponding to the column customer_num, this entry retrieves any of three numbers: 102|105|118 2. You can use the BY NAME option when the eld names on the screen form have the same names as the corresponding column names in column-list. If you do not, you must specify a screen record or name the elds explicitly in eld-list. 3. The CONSTRUCT statement is terminated when the user enters ESC or the key specied as the Accept key in the OPTIONS statement. For single-item CONSTRUCTs, pressing RETURN is equivalent to pressing the Accept key, unless the INPUT WRAP option is in effect. For multiple-item CONSTRUCTs, a RETURN after the last item is equivalent to pressing the Accept key, unless INPUT WRAP is in effect. 4. By default, both ESC and Interrupt exit from CONSTRUCT statements. If the DEFER INTERRUPT statement has been executed, an Interrupt sets the global variable int_ag to nonzero and terminates the CONSTRUCT statement (but not the 4GL program). Otherwise, an Interrupt causes an immediate program stop.

7-34

INFORMIX-4GL Statement Syntax

CONSTRUCT

5. In addition to the RETURN, ESC, ARROW, and Interrupt keys, the user can employ the following keys for editing during a CONSTRUCT statement: CTRL-A CTRL-D CTRL-H CTRL-L CTRL-R CTRL-X toggles between insert and typeover mode. deletes characters from the current cursor position to the end of the eld. moves the cursor nondestructively one space to the left inside a eld. It is equivalent to pressing the [] key. moves the cursor nondestructively one space to the right inside a eld. It is equivalent to pressing the [] key. redisplays the screen. deletes the character beneath the cursor.

6. The user can query for only those elds displayed on the screen that you have specied in the FROM clause or implied in the BY NAME clause. The number of elds in the FROM clause must be the same as the number of columns in the ON clause. The order of elds in the FROM clause must match the order of columns in the ON clause. INFORMIX-4GL constructs char-variable by associating the column name in the ON clause with the search condition that the user entered into the corresponding eld in the FROM clause. 7. The UPSHIFT and DOWNSHIFT attributes work during a CONSTRUCT statement. The COMMENTS attribute works, but with the following restriction: if a eld that displays a comment is too short to hold the search criteria that the user enters, INFORMIX-4GL opens a work space on the Comment line, erasing any comment that is displayed. 8. If the column names in a CONSTRUCT BY NAME statement are associated with eld names in a screen array, the construct takes place in the rst row of the screen array. If you want to use screen-array eld names in the FROM clause of a CONSTRUCT statement, then you must use the notation screen-record [n ]. eld-name to specify the row in which the construct takes place. 9. You can use the information stored in char-variable in the WHERE clause of a PREPAREd SELECT statement to retrieve a set of rows from the database. 10. A compile-time error results if you use the BY NAME clause when the column names include an owner name. You must use the FROM clause to specify table aliases in the eld-list when any column names contain an owner name.

INFORMIX-4GL Statement Syntax

7-35

CONSTRUCT

11. When you use screen-record.* or table.* as shorthands for explicit lists, be sure that the order of the elds implied in the screen-record.* notation corresponds to the order of the columns implied in the screen-record.* notation. The order of the elds in screen-record.* depends on its denition in the screen form. The order of the columns in table.* depends on the order in the syscolumns system catalog at the time you compile your program. If you have used ALTER TABLE to change the order or number of the columns in table since you compiled your program, you may need to modify your program and the forms that depend on it. 12. Any screen attributes specied in attribute-list apply to all the elds in eld-list or screen-record. 13. If you use the ATTRIBUTE clause, none of the default attributes listed in syscolatt or in the form specication le for elds in eld-list or screenrecord apply. The attribute-list temporarily overrides any attributes specied in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these elds. 14. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

You can specify zero or one of the keywords in the left-hand columns, and from zero to three from the right-hand column (but some terminals may not support some combinations). On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. Do not include the equal ( = ) sign, which in this table shows the effect on monochrome terminals of keywords that specify color. These keywords cannot produce the effects indicated unless the termcap or terminfo les and the physical terminals support the attribute. (See Appendix I, Modifying termcap and terminfo.) 15. On UNIX systems that use terminfo les rather than termcap, INFORMIX-4GL does not support attributes that specify colors, and the only valid attribute-list keywords are REVERSE and UNDERLINE. 16. You must rst execute OPEN FORM or OPEN WINDOW WITH FORM before you can use the CONSTRUCT statement.

7-36

INFORMIX-4GL Statement Syntax

CONSTRUCT

Example
The following program fragment illustrates the use of the CONSTRUCT statement to specify the search condition of a WHERE clause. The cursor_1 cursor is DECLAREd and used to execute the query.
CONSTRUCT query_1 ON order_num, customer_num, order_date, ship_date FROM order_num, customer_num, order_date, ship_date ATTRIBUTE(BOLD) LET s1 = "select * from orders where ", query_1 PREPARE s_1 FROM s1 DECLARE cursor_1 CURSOR FOR s_1 FOREACH cursor_1 INTO order_rec.* ... END FOREACH

Related Statements
DECLARE, PREPARE, OPEN FORM, OPTIONS, SELECT

INFORMIX-4GL Statement Syntax

7-37

CONTINUE

CONTINUE
Overview
Use the CONTINUE statement to cause a FOR, FOREACH, or WHILE statement to start a new cycle immediately, if the conditions permit, or to return to the menu from an option in the MENU statement.

Syntax
CONTINUE { FOR | FOREACH | MENU | WHILE }

Explanation
CONTINUE FOR FOREACH MENU WHILE

is a required keyword. is a required keyword in a FOR statement. is a required keyword in a FOREACH statement. is a required keyword in a MENU statement. is a required keyword in a WHILE statement.

Related Statements
END, EXIT

7-38

INFORMIX-4GL Statement Syntax

CREATE AUDIT

CREATE AUDIT
Overview
Use the CREATE AUDIT statement to create an audit trail le, and to start writing the audit trail.

Syntax
CREATE AUDIT FOR table-name IN "pathname"

Explanation
CREATE AUDIT FOR table-name
IN

are required keywords. is the name of the table for which to create an audit trail le. is a required keyword. is the full pathname for the audit trail le. It must be enclosed in quotation ( " ) marks.

pathname

Notes
1. You create audit trails to keep a record of all modications of a table. An audit trail is a complete history of all additions, deletions, and updates to the table. INFORMIX-4GL can use the audit trail to reconstruct the table from a backup copy made at the time the audit trail is created. (See the RECOVER TABLE statement.) See the section Audit Trails in Chapter 3 for more information. 2. If an audit trail le with the same pathname already exists for the same table, the CREATE AUDIT statement does nothing. If an audit trail le for the same table exists with a different pathname, INFORMIX-4GL displays an error message. 3. Make a backup copy of your database les as soon as you run the CREATE AUDIT statement, but before you make any further changes to the database. (See the RECOVER TABLE statement for an example.) If possible, put the audit trail le on a different physical device from the one that holds your data, so that a failure of one does not damage the data on the other. 4. Audit trails slow INFORMIX-4GL slightly because each alteration of the table is recorded in the audit trail le, as well as in the database les.
INFORMIX-4GL Statement Syntax 7-39

CREATE AUDIT

5. You must own table-name or have DBA status to use the CREATE AUDIT statement. 6. You must set execute permission for all directories below root in pathname for each class of user (owner, owners group, and public) that accesses your database. 7. You cannot create an audit le for a view. 8. You cannot create a cluster index on a table that has an audit trail.

Example
CREATE AUDIT FOR orders IN "/dbdir/safe"

Related Statements
DROP AUDIT, RECOVER TABLE

7-40

INFORMIX-4GL Statement Syntax

CREATE DATABASE ( O )

CREATE DATABASE ( O )
Overview
Use the CREATE DATABASE statement to create a new database. INFORMIX-4GL will create the system catalogs that will contain the data dictionary describing the structure of the database. The database that you create automatically becomes the current database.

Syntax
CREATE DATABASE database-name [ WITH LOG IN "pathname" [ MODE ANSI ] ]

Explanation
CREATE DATABASE

are required keywords. is the name that you assign to the database. The databasename can be a program variable of type CHAR containing the name of the database you want to create. are optional keywords to support transactions. is the full pathname, enclosed in quotation ( " ) marks, of the transaction log le. are optional keywords that specify the database as MODE
ANSI.

database-name

WITH LOG IN

pathname
MODE ANSI

Notes
1. INFORMIX-4GL creates a subdirectory in the current directory with the name database-name.dbs. All of the system catalogs, data, and index les will be placed in this subdirectory, except for tables that you explicitly instruct INFORMIX-4GL to create elsewhere. 2. A database name can be up to 10 characters long and can contain only letters, digits, and underscores ( _ ). The rst character must be a letter. If you store more than one database in a single directory, the database names must be unique.

INFORMIX-4GL Statement Syntax

7-41

CREATE DATABASE ( O )

3. For a user to have access to a database, the user must have execute (search) permission for each directory in the full pathname of database-name.dbs, as well as appropriate database privileges. (See the GRANT statement later in this chapter.) 4. See Appendix B for a description of the system catalogs. 5. The WITH LOG IN clause creates a transaction log le. Without this le, you cannot use the BEGIN WORK, COMMIT WORK, or the ROLLBACK WORK statements. You can use the START DATABASE statement to assign a log le to an existing database. See the section Transactions in Chapter 3 for further details. You must include the WITH LOG IN keywords and specify a transaction log le when you use the MODE ANSI keywords in the CREATE DATABASE statement. 6. A database created as MODE ANSI supports implicit transactions. All statements automatically appear within a transaction. (Do not use the BEGIN WORK statement in a program that accesses a MODE ANSI database.) You explicitly terminate a transaction when you issue a COMMIT WORK or ROLLBACK WORK statement. 7. You can determine the type of database that a user selects by checking the warning ag after a DATABASE statement in the SQLCA.SQLAWARN structure. See the section SQLCA Record in Chapter 3 for more information about the SQLCA.SQLAWARN character string. 8. You cannot drop MODE ANSI from a database. Once created or started as such, a database remains MODE ANSI. 9. The CREATE DATABASE statement cannot appear in a multi-statement PREPARE.

Examples
This CREATE DATABASE statement creates the stores database with a transaction log le:
CREATE DATABASE stores WITH LOG IN "/s/log/stores.log"

This CREATE DATABASE statement creates the stores database as MODE ANSI:
CREATE DATABASE stores WITH LOG IN "/u/myname/stores.log" MODE ANSI

7-42

INFORMIX-4GL Statement Syntax

CREATE DATABASE ( O )

Related Statements
DROP DATABASE, GRANT, START DATABASE

INFORMIX-4GL Statement Syntax

7-43

CREATE INDEX

CREATE INDEX
Overview
Use the CREATE INDEX statement to create an index for one or more columns in a table, and optionally to cluster the physical table in the order of the index. When more than one column is listed, the concatenation of the set of columns is treated as a single composite column for indexing.

Syntax
CREATE [ UNIQUE ] [ CLUSTER ] INDEX index-name ON table-name ( column-name [ ASC | DESC ] [ , . . . ] )

Explanation
CREATE INDEX are required keywords. UNIQUE CLUSTER

is a keyword to prevent duplicate entries in the column or composite column to which the index applies. is an optional keyword that causes the physical table to be ordered according to the order of the index. is the SQL identier you want to assign to the index. You must assign a different identier to each index in the database. is a required keyword. is the name of the table containing the column or columns that you want to index. is the name of a column to be indexed. To create an index that applies to several columns, enter a list of column names, separated by commas. All the columns must belong to the same table. is a keyword that species an index that INFORMIX-4GL maintains in ascending order. ASC is the default. is a keyword that species an index that INFORMIX-4GL maintains in descending order.

index-name

ON

table-name column-name

ASC DESC

7-44

INFORMIX-4GL Statement Syntax

CREATE INDEX

Notes
1. When INFORMIX-4GL executes the CREATE INDEX statement, it locks table-name in EXCLUSIVE mode. If another process is using table-name, INFORMIX-4GL cannot execute CREATE INDEX and returns an error. 2. You can include up to eight columns in a composite index. 3. The total length of all columns indexed in a single CREATE INDEX statement cannot exceed 120 bytes. 4. See the section Indexing Strategy in Chapter 3 for a discussion of indexing strategy. 5. The CREATE CLUSTER INDEX statement fails if a CLUSTER index already exists. 6. The CREATE CLUSTER INDEX statement fails if the table has an audit trail. 7. Only one index on a particular sequence of columns is allowed. 8. You cannot use the ROLLBACK WORK statement to undo a CREATE INDEX statement. 9. When you create a table, you can specify that a column or composite column will allow only unique values. You use the UNIQUE keyword in the CREATE TABLE statement. 10. You cannot create an ascending index on a column dened as UNIQUE in a CREATE TABLE statement. 11. A column list dened as having a UNIQUE CONSTRAINT in a CREATE TABLE statement receives a unique ascending composite index. You cannot use the CREATE INDEX statement to create an identical unique composite index. 12. In a composite index, you can include a column dened as UNIQUE. Similarly, in a composite index you can include a composite column list dened as UNIQUE. However, the column list in the CREATE INDEX statement cannot be identical to the column list dened as UNIQUE in the CREATE TABLE statement. 13. When more than one column is listed, the concatenation of the set of columns is treated as a single composite column for the purpose of indexing. 14. DISTINCT is a synonym for UNIQUE.

INFORMIX-4GL Statement Syntax

7-45

CREATE INDEX

Examples
CREATE UNIQUE INDEX i_ordnum ON orders (order_num)

CREATE CLUSTER INDEX i_ordnum2 ON orders (order_num DESC)

Related Statements
ALTER INDEX, CREATE TABLE, DROP INDEX

7-46

INFORMIX-4GL Statement Syntax

CREATE SYNONYM

CREATE SYNONYM
Overview
Use the CREATE SYNONYM statement to provide an alternative name for a table or view.

Syntax
CREATE SYNONYM synonym FOR table-name

Explanation
CREATE SYNONYM synonym
FOR

are required keywords. is an SQL identier. is a required keyword. is the name of a table or view.

table-name

Notes
1. In a MODE ANSI database, the name of a synonym is qualied by the owner of the synonym (owner. synonym). You must specify owner when you refer to a synonym owned by another user. The use of the prex owner is optional in a non-MODE ANSI database. INFORMIX-4GL does check the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 of this manual. 2. A user has no privileges under a synonym that were not granted for the table to which it applies. 3. When a synonym is created in an INFORMIX-4GL program, the owner of the synonym is the person who runs the program. 4. Synonyms are not to be confused with table aliases in SELECT statements. A synonym persists until you drop it with the DROP SYNONYM statement. Table aliases are useful only in the SELECT statement. 5. The CREATE SYNONYM statement cannot be rolled back. 6. For a database created or started as MODE ANSI, owner.synonym must be unique among all the synonyms, tables, and views in the database. In a non-MODE ANSI database, synonym must be unique.
INFORMIX-4GL Statement Syntax 7-47

CREATE SYNONYM

Example
CREATE SYNONYM cust FOR customer

Related Statements
DROP SYNONYM, SELECT

Note: Synonyms are very useful for referencing external objects with INFORMIX-OnLine. Refer to the INFORMIX-OnLine Programmers Manual for more information.

7-48

INFORMIX-4GL Statement Syntax

CREATE TABLE ( O )

CREATE TABLE ( O )
Overview
Use the CREATE TABLE statement to create a new table in the current database.

Syntax
CREATE [ TEMP ] TABLE table-name ( column-name datatype [ NOT NULL ] [ UNIQUE [ CONSTRAINT constr-name ] ] [ , . . . ] [ UNIQUE ( unique-col-list ) [ CONSTRAINT constr-name ] ] [ , . . . ] ) [ WITH NO LOG ] [ IN pathname ]

Explanation
CREATE TABLE TEMP

are required keywords. is an optional keyword. is the SQL identier that you assign to the table. The rst ten characters must be unique within a database. is the SQL identier that you assign to each column. species the data type for each column. (See the following list for valid SQL data types.) are optional keywords to prevent entry of NULL values. is an optional keyword specifying that the column or composite unique-col-list cannot contain duplicate values. is a list (in parentheses) of the names of columns to include in a composite UNIQUE CONSTRAINT. is a keyword to indicate that constr-name is assigned in the statement. is the name of the UNIQUE CONSTRAINT. A constr-name must be a valid identier that does not conict with an existing constraint name. It can be optionally prexed with the username of the owner of the table or, if you have DBA privileges, the username of another user.

table-name column-name datatype

NOT NULL UNIQUE

(unique-col-list)
CONSTRAINT

constr-name

INFORMIX-4GL Statement Syntax

7-49

CREATE TABLE ( O )

WITH NO LOG

are optional keywords that prevent logging of TEMP tables. In a database that uses logging, the default is to log TEMP tables also. is an optional keyword. species the full pathname in which to store the database table, with no extension to the lename. A pathname cannot be longer than 64 characters and must be enclosed within quotes ( " ). A pathname is of the form:
[ /directory-name/ . . . ] lename

IN

pathname

A list of valid SQL data types follows:

CHAR ( n ) CHARACTER SMALLINT INTEGER INT

is a character string of length n (where 1 n 32,511). is a synonym for CHAR. is a whole number from -32,767 to +32,767. is a whole number from -2,147,483,647 to +2,147,483,647. is a synonym for INTEGER. signicant digits (precision) and n ( m) digits to the right of the decimal point (scale). See the section Database Data Types in Chapter 3 for more information.

DECIMAL [(m[,n])] is a decimal oating-point number with a total of m ( 32)

DEC NUMERIC SMALLFLOAT REAL FLOAT [(n)]

is a synonym for DECIMAL. is a synonym for DECIMAL. is a binary oating-point number corresponding to the oat data type in the C language. is a synonym for SMALLFLOAT. is a binary oating-point number corresponding to the double data type in the C language. You can use n to specify the precision of a FLOAT data type, although the precision is ignored by INFORMIX-4GL. n must be a whole number between 1 and 14. is a synonym for FLOAT. is a DECIMAL type number, displayed with leading $. MONEY (m) = DECIMAL(m,2) and MONEY = DECIMAL(16,2). See the section Database Data Types in Chapter 3 for more information.

DOUBLE PRECISION MONEY [(m[,n])]

7-50

INFORMIX-4GL Statement Syntax

CREATE TABLE ( O )

SERIAL [(n)]

is a sequential integer assigned automatically by 4GL. You can assign an initial value n. The default starting integer is 1. is a date entered as a character string in one of the formats described in the following notes. is a moment in time that can include the year, month, day, hour, minute, second, and fraction of a second. See the following notes and the section Database Data Types in Chapter 3 for more information. is a positive or negative span of time that can include years and months, or else days, hours, minutes, seconds, and fractions of a second. See the following notes and the section Database Data Types in Chapter 3 for more information. See also Appendix J, Working with DATETIME and INTERVAL Data.

DATE DATETIME

INTERVAL

Notes
1. In a database created as MODE ANSI, the name of a table is qualied by the owner of the table (owner. table-name). You must specify owner when you refer to a table owned by another user. The use of the prex owner is optional in a non-MODE ANSI database. INFORMIX-4GL checks the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 of this manual. 2. Table names must be unique within a database. If the database is MODE ANSI, the combination owner.tablename must be unique. 3. Column names must be unique within each table, but you can use duplicate names in different tables in the same database. See SQL Identiers in Chapter 3 for guidelines on table names and column names. 4. Temporary tables created with the TEMP option exist for the duration of the program. 5. Users with CONNECT privilege can create temporary tables. 6. The default value in a column is NULL unless you include the NOT NULL keywords after the data type of the column. 7. If you designate a column as NOT NULL, users must enter a value into this column when performing an INSERT or UPDATE to the table.

INFORMIX-4GL Statement Syntax

7-51

CREATE TABLE ( O )

8. When you create a table in a database that is not MODE ANSI, all tablelevel privileges (except ALTER) are automatically granted to all users (PUBLIC). To restrict access privileges at the table level, you must revoke all privileges and grant those you want. In a database created as MODE ANSI, no default table-level privileges exist. You must explicitly grant these privileges. 9. You can specify no more than one SERIAL column in a table. 10. Enter DATE data type values in the sequence of month, day, and year, with any non-numeric character, including a blank, as a separator. Represent the month as the number of the month (January = 1 or 01, February = 2 or 02, and so on). Represent the day as the day of the month (1 or 01, 2 or 02, and so on). The year is stored as a four-digit number (0001 to 9999). If you enter two digits yy for the year, INFORMIX-4GL assumes that the year is 19yy. The following values are all acceptable representations of June 1, 1989: 06/01/89, 6.1.89, and 6-1-1989. 11. The DATE type is actually stored as the integer number of days since December 31, 1899. You can sort DATE columns and make chronological comparisons between two DATE columns. 12. The following table shows the le space requirements (in bytes) for each data type:
SERIAL SMALLINT INTEGER SMALLFLOAT FLOAT CHAR(n) DECIMAL(m,n) MONEY(m,n) DATE DATETIME INTERVAL 4 2 4 4 8 n 1 + m/2 1 + m/2 4 Depends on precision (see below) Depends on precision (see below)

Values in a DATETIME column are stored as decimal numbers, containing a sequence of digits representing the following elds: year, month, day, hour, minute, second, and fraction(n). All elds of a DATETIME column occupy two digits, except for the year and fraction elds. The year eld requires four digits. The fraction eld requires n digits, rounded up to an even number. The number of bytes required for a DATETIME column is equal to half the total number of digits for all elds, plus 1. Values in an INTERVAL column are stored as decimal numbers, containing a sequence of digits representing the following elds: year and month, or else year, month, day, hour, minute, second, and fraction(n). All
7-52 INFORMIX-4GL Statement Syntax

CREATE TABLE ( O )

elds of an INTERVAL column are represented by two digits, except for the rst eld and the fraction eld. The number of digits in the rst eld is two, unless otherwise specied as part of the qualier. The fraction eld requires n digits. The number of bytes required for an INTERVAL column is equal to half the total number of digits for all elds, rounded up to an even number, plus 1. 13. The CREATE TABLE statement cannot be rolled back. 14. You can use the UNIQUE keyword to require that a single column or set of columns accept only unique data. A column or composite column list specied as UNIQUE is referred to as having a UNIQUE CONSTRAINT. 15. Each column in unique-col-list must be a column in the table and must not appear in the list more than once. 16. You cannot insert duplicate values into a UNIQUE column. 17. You cannot create an ascending index on a UNIQUE column. You cannot create an ascending composite index on an identical composite column list declared as UNIQUE. 18. You can include a UNIQUE column in a composite index created with the CREATE INDEX statement. 19. Use the ALTER TABLE statement to add or drop a UNIQUE CONSTRAINT from a column or composite column list. You can query the sysconstraints system catalog for the names of constraints. 20. You can include up to eight columns in a unique-col-list. The total length of all the columns in a unique-col-list cannot exceed 120 bytes. 21. If you do not specify a constr-name, INFORMIX-4GL generates one using the template u<tabid>_<index number>. If this name conicts with an existing identier, INFORMIX-4GL returns an error, and you must supply constr-name. 22. INFORMIX-4GL implements the UNIQUE CONSTRAINT by creating a unique index for every column declared as UNIQUE in the CREATE TABLE statement. A row is added to the sysindexes le for each index. Each index name is created with the format
[space]<tabid>_<index number>.

23. The keyword DISTINCT is a synonym for UNIQUE. 24. If the pathname in an IN clause species a lename that is different from the table-name, always use the table-name (rather than the lename) to refer to the table in subsequent SQL statements.

INFORMIX-4GL Statement Syntax

7-53

CREATE TABLE ( O )

25. The pathname in an IN clause can specify any valid directory and is not restricted to the directory that contains the current database. Use this feature if your database is becoming too large for your current disk volume. 26. If you use the WITH NO LOG keywords in a CREATE TABLE statement and the database does not use logging, the WITH NO LOG option is ignored. The WITH NO LOG option is supported on a MODE ANSI database. 27. Once you create a temporary table WITH NO LOG, you cannot turn on logging. A temporary table is, therefore, always logged or never logged.

Examples
The sequence of statements that creates the stores database follows:
CREATE DATABASE stores CREATE TABLE customer ( customer_num SERIAL(101), fname CHAR(15), lname CHAR(15), company CHAR(20), address1 CHAR(20), address2 CHAR(20), city CHAR(15), state CHAR(2), zipcode CHAR(5), phone CHAR(18) ) CREATE TABLE orders ( order_num order_date customer_num ship_instruct backlog po_num ship_date ship_weight ship_charge paid_date )

SERIAL(1001), DATE, INTEGER, CHAR(40), CHAR(1), CHAR(10), DATE, DECIMAL(8,2), MONEY(6), DATE

CREATE TABLE items ( item_num order_num 7-54 INFORMIX-4GL Statement Syntax

SMALLINT, INTEGER,

CREATE TABLE ( O )

stock_num manu_code quantity total_price ) CREATE TABLE stock ( stock_num manu_code description unit_price unit unit_descr )

SMALLINT, CHAR(3), SMALLINT, MONEY(8)

SMALLINT, CHAR(3), CHAR(15), MONEY(6), CHAR(4), CHAR(15)

CREATE TABLE manufact ( manu_code CHAR(3), manu_name CHAR(15) ) CREATE TABLE state ( code sname )

CHAR(2), CHAR(15)

The following statement creates the tab1 table. In tab1, column c1 is UNIQUE and the constraint is named uc1. A UNIQUE CONSTRAINT is also applied to the composite columns c3 and c4.
CREATE TABLE tab1 ( c1 INTEGER NOT NULL UNIQUE CONSTRAINT uc1, c2 INTEGER, c3 INTEGER NOT NULL, c4 CHAR(10) NOT NULL, UNIQUE (c3,c4) )

INFORMIX-4GL Statement Syntax

7-55

CREATE TABLE ( O )

The following statement creates the employee table. The data for the table is stored in the le /a/work/employ.dat. The index information is stored in the le /a/work/employ.idx.
CREATE TABLE employee ( employ_num SERIAL(101), fname CHAR(15), lname CHAR(15), address CHAR(20), city CHAR(15), state CHAR(2), zipcode CHAR(5), phone CHAR(18) hire_date DATE ) IN "/a/work/employ"

The following example shows a use of the DATETIME and INTERVAL data types:
CREATE TABLE tv_programs ( prog_title CHAR(32), air_date DATETIME YEAR TO DAY NOT NULL, air_time DATETIME HOUR TO MINUTE, duration INTERVAL HOUR TO SECOND )

The following example shows how to prevent logging of TEMP tables in a database that uses logging:
CREATE TEMP TABLE tab2 (fname CHAR(15), lname CHAR(15)) WITH NO LOG

Related Statements
ALTER TABLE, CREATE DATABASE, CREATE INDEX, DROP DATABASE, DROP TABLE, GRANT, REVOKE

7-56

INFORMIX-4GL Statement Syntax

CREATE VIEW

CREATE VIEW
Overview
Use CREATE VIEW to create a new view based on existing tables and views in the database.

Syntax
CREATE VIEW view-name [ ( column-list ) ] AS SELECT-statement [ WITH CHECK OPTION ]

Explanation
CREATE VIEW

are required keywords. is an SQL identier. is a list of one or more identiers that name the columns of view-name. is a required keyword. is a SELECT statement. are optional keywords.

view-name column-list
AS SELECT-statement WITH CHECK OPTION

Notes
1. In a database created as MODE ANSI, the name of a view is qualied by the owner of the view (owner.view-name). You must specify owner when you refer to a view owned by another user. The use of the prex owner. is optional in a non-MODE ANSI database. INFORMIX-4GL does check the accuracy of owner if you include it in a statement, however. See the section Owner Naming in Chapter 3 of this manual. 2. Except for the statements in the following list, you can use a view in any SQL statement (including form specications) where you can use a table.
ALTER TABLE ALTER INDEX CREATE INDEX DROP INDEX LOCK TABLE RENAME TABLE

The view behaves like a table with the name view-name and consists of the set of rows and columns returned by the SELECT-statement each time the
INFORMIX-4GL Statement Syntax 7-57

CREATE VIEW

SQL statement is executed using the view. The view reects changes to the

underlying tables, but with one exception. If the view is dened with a SELECT * clause, it has only the columns that are in the underlying tables at the time the view is created. New columns added subsequently to the underlying tables using the ALTER TABLE statement will not appear in the view. See the section Views in Chapter 3 for more information. 3. When you do not specify column-list for view-name, the view inherits the column names of the underlying tables. If the SELECT-statement returns an expression, the corresponding column in the view is called a virtual column. You must provide a name for virtual columns. You must also provide a column name when the select-list has duplicate column names when the table prexes are stripped. For example, when both orders.order_num and items.order_num appear in the select-list, you must provide two separate column names to label them in the CREATE VIEW statement. 4. Data types of the columns of the view are inherited from the tables from which they come. Data types of virtual columns are determined from the nature of the expression. 5. For a database created as MODE ANSI, owner.view-name must be unique among all the tables, views, and synonyms in the database. In a nonMODE ANSI database, view-name must be unique. 6. You can dene a view in terms of other views, except that you must abide by the restrictions on queries listed in the section Querying Through Views in Chapter 3. 7. The SELECT-statement cannot have an ORDER BY clause nor a UNION operator. 8. You must have SELECT privilege on all columns from which the view is derived. 9. The WITH CHECK OPTION clause instructs INFORMIX-4GL to ensure that all modications to the underlying tables made through the view satisfy the denition of the view. 10. The CREATE VIEW statement cannot be rolled back.

Example
CREATE VIEW palo_alto AS SELECT * FROM customer WHERE city = "Palo Alto"

7-58

INFORMIX-4GL Statement Syntax

CREATE VIEW

Related Statements
CREATE TABLE, DROP VIEW

INFORMIX-4GL Statement Syntax

7-59

CURRENT WINDOW

CURRENT WINDOW
Overview
Use the CURRENT WINDOW statement to make a window the current or topmost window.

Syntax
CURRENT WINDOW IS { window-name | SCREEN }

Explanation
CURRENT WINDOW IS

are required keywords. is the name of the window that you want to be the current window. is a keyword that refers to the entire screen.

window-name
SCREEN

Notes
1. A window becomes completely visible when it becomes the current window. In the process, other inactive windows may be obscured. 2. All input and output is done in the current window. 3. If window-name contains a screen form, the screen form becomes the current form. 4. The terminal screen is the current window when a program starts. 5. If you specify SCREEN as the window-name, the entire screen becomes the current window. 6. See also the CLEAR statement, which removes any text from the screen, and makes the entire screen the current window. 7. The DISPLAY ARRAY, INPUT, INPUT ARRAY, and MENU statements run in the current window. When you change the current window while one of these statements is active and then resume the statement, the original window is restored as the current window. For example, you can use an ON KEY clause in an INPUT statement to allow the user to open a new win-

7-60

INFORMIX-4GL Statement Syntax

CURRENT WINDOW

dow by pressing a specic key during input. When the user presses the designated key, INFORMIX-4GL executes the statements in the ON KEY clause and then resumes input from the window that was current before the ON KEY break. 8. The context of each window includes the values for the Prompt, Message, Form, and Comment lines. When a window becomes the current window, these values are restored. 9. When working with multiple windows, INFORMIX-4GL maintains a list or stack of all open windows. It adds the current window to its window list whenever you open a new window. The new window then becomes the current window. When you close a window, INFORMIX-4GL removes it from its window list. The topmost window (of those that remain) becomes the current window. 10. When you specify a current window, INFORMIX-4GL adjusts the window list by moving the new current window to the top, and closing the gap in the list left by this window.

Examples
CURRENT WINDOW IS win1 CURRENT WINDOW IS SCREEN

Related Statements
CLEAR WINDOW, CLOSE WINDOW, OPEN WINDOW, OPTIONS

INFORMIX-4GL Statement Syntax

7-61

DATABASE

DATABASE
Overview
Use the DATABASE statement to declare an accessible database as the current database.

Syntax
DATABASE database-name [ EXCLUSIVE ]

Explanation
DATABASE

is a required keyword. is the name of a database, or a program variable that evaluates to the name of a database. is an optional keyword.

database-name
EXCLUSIVE

Notes
1. If you want to specify a database that does not reside in your current directory or in a directory specied by the DBPATH environment variable (described in Appendix C), you must follow the DATABASE keyword with a program variable that evaluates to the full pathname of the database (excluding the .dbs extension). 2. In an INFORMIX-4GL program, the DATABASE statement can serve two purposes, one procedural and the other non-procedural. It makes the named database the current database (procedural), and it tells the compiler where to nd information about variables dened LIKE columns in a table (non-procedural). To serve the non-procedural purpose, the DATABASE statement must occur outside any routine and precede the GLOBALS statements when you use indirect data typing with the LIKE clause. The database-name must be explicitly expressed and not given as a program variable. You cannot use the EXCLUSIVE keyword in this context. If you use the DATABASE statement in this non-procedural way, INFORMIX-4GL begins the MAIN program block with the database-name as the current database. Ordinarily, you use only one database, and the preceding procedure is enough. If you do not have global variables dened LIKE database columns, but still want to interact with a database, you can use the
7-62 INFORMIX-4GL Statement Syntax

DATABASE

DATABASE statement in a purely procedural way. In this case, it must occur within a routine and must follow any DEFINE statements within that routine. In this case, database-name can be a program variable, and you can use the EXCLUSIVE keyword.

3. The DATABASE statement closes any other current database. 4. If you close one database and open another in a program, you cannot dene variables LIKE columns in the second database. 5. The EXCLUSIVE option opens the database in an exclusive mode and allows only the current user access to the database. To allow others access to the database, you must execute the CLOSE DATABASE statement and then reopen the database. 6. You can determine the type of database a user selects by checking the warning ag after a DATABASE statement in the SQLCA.SQLAWARN structure. See the section SQLCA Record in Chapter 3 for more information about SQLCA.SQLAWARN. 7. You cannot include the DATABASE statement in a multi-statement PREPARE.

Example
DATABASE stores

Related Statements
CREATE DATABASE, DROP DATABASE, CLOSE DATABASE

INFORMIX-4GL Statement Syntax

7-63

DECLARE

DECLARE
Overview
Use the DECLARE statement to assign a cursor name to a SELECT or INSERT statement. A cursor is required for a SELECT statement that selects more than one row.

Syntax
DECLARE cursor-name [ SCROLL ] CURSOR [ WITH HOLD ] FOR { SELECT-statement [ FOR UPDATE [ OF column-list ] ] | INSERT-statement | statement-id }

Explanation
DECLARE

is a required keyword. is an INFORMIX-4GL identier. is an optional keyword that can be used only with a statement or a statement_id of a SELECT statement that you PREPAREd. are required keywords. are optional keywords to prevent the cursor from being closed when each transaction ends. is a SELECT statement. are keywords that are required if the cursor will be used to modify existing rows. is an optional keyword. is a list of column names from tables listed in the FROM clause of SELECT-statement. is an INSERT statement. is the identier of an INSERT or SELECT statement that you previously PREPAREd.

cursor-name
SCROLL

CURSOR FOR WITH HOLD SELECT-statement FOR UPDATE OF

column-list
INSERT-statement

statement-id

Notes
1. You must DECLARE a SELECT cursor before you can use it in an OPEN, FETCH, FOREACH, DELETE, UPDATE, or CLOSE statement. You must
7-64 INFORMIX-4GL Statement Syntax

DECLARE

DECLARE an INSERT cursor before you can use it in an OPEN, PUT, FLUSH, or CLOSE statement.

2. You can DECLARE a cursor as SCROLL or WITH HOLD or both. 3. SCROLL cursors, INSERT cursors, and cursors WITH HOLD are Informix extensions to ANSI standard syntax. You receive a warning if you compile with the -ansi ag, or if you have set the DBANSIWARN environment variable and include the SCROLL, INSERT, or WITH HOLD keywords in a program. 4. Unless you include the WITH HOLD keywords, INFORMIX-4GL closes the cursor after each transaction. (A CLOSE DATABASE statement closes all cursors, including cursors WITH HOLD.) 5. The following rules apply when you use cursor manipulation statements in a non-MODE ANSI database with explicit transactions:

You must OPEN and CLOSE a regular cursor that is FOR UPDATE and
an INSERT cursor within a transaction.

All FLUSH and PUT statements must appear within a transaction. Each UPDATE, INSERT, or DELETE action must take place within a
transaction.

You can OPEN and CLOSE a cursor WITH HOLD that is FOR UPDATE
outside a transaction. Any FETCH using it, however, must take place within a transaction. These requirements are automatically satised if the current database is a MODE ANSI database. 6. Unlike other cursors, a cursor WITH HOLD is not closed when you execute a COMMIT WORK or ROLLBACK WORK statement. You must explicitly CLOSE a cursor WITH HOLD. (A CLOSE DATABASE statement closes all cursors, including cursors WITH HOLD.) 7. You must include the SCROLL keyword in the DECLARE statement for a SELECT cursor if you are going to issue a statement that includes the PREVIOUS, LAST, FIRST, CURRENT, RELATIVE, or ABSOLUTE keywords. SCROLL enables a cursor to FETCH rows in random order. 8. You must specify the statement-id to identify a SELECT or INSERT statement in a previous PREPARE statement. 9. The column names in an OF column-list clause do not need to be in the select-list of the SELECT clause. 10. If the SELECT statement has no INTO clause, the subsequent FETCH statement must specify INTO variable-list.

INFORMIX-4GL Statement Syntax

7-65

DECLARE

11. Do not use INTO with an array element subscripted by a variable in the SELECT statement because the subscript is evaluated at the time of the DECLARE, not at the time of any subsequent FETCH. You can use a constant to indicate the array element. Use FETCH INTO when the output variable is an array element subscripted by a variable or a constant. 12. You cannot use the FOR UPDATE clause in the DECLARE statement for a SELECT cursor that includes the SCROLL keyword or an ORDER BY clause. 13. If you use the FOR UPDATE clause, the SELECT statement is limited to a single table. 14. You must use the FOR UPDATE clause in the DECLARE statement for a non-scrolling SELECT cursor if you will later use either the UPDATE or the DELETE statement with the WHERE CURRENT OF cursor-name option. The cursor FOR UPDATE can include or omit WITH HOLD. 15. If you specify one or more columns in the FOR UPDATE clause, you can update only those columns in a subsequent UPDATE WHERE CURRENT OF statement. (If you do not specify any columns in the FOR UPDATE clause, you can update any column in a subsequent UPDATE WHERE CURRENT OF statement.) 16. When you DECLARE a cursor FOR UPDATE, each FETCH executed on that cursor locks the FETCHed row in exclusive mode. For a database without transactions, the lock is released when you execute the next FETCH statement or when you CLOSE the cursor (whichever occurs rst), regardless of whether you UPDATE the row. For a database with transactions, each row that you UPDATE remains locked for the duration of the transaction. These locks are released only when you end the transaction (issue a COMMIT WORK or ROLLBACK WORK statement). See the sectionLocking in Chapter 3 for a more detailed description of table-level and row-level locking. 17. If your database has a transaction log but is not MODE ANSI, you must issue a BEGIN WORK statement before you OPEN a cursor that you DECLAREd FOR UPDATE but not WITH HOLD. (You can DECLARE a cursor WITH HOLD FOR UPDATE outside a transaction, but you cannot roll back any changes to a non-MODE ANSI database that the cursor performs outside a transaction. In this situation, each UPDATE is automatically committed as a singleton transaction.)

7-66

INFORMIX-4GL Statement Syntax

DECLARE

18. INFORMIX-4GL evaluates the variables in a DECLARE statement at the time when you OPEN the cursor, except for those variables that include subscripts. INFORMIX-4GL evaluates the subscript when you DECLARE the cursor and evaluates the variable when you OPEN the cursor. In the following example, INFORMIX-4GL selects rows where the value in the customer_num column equals 106:
LET a = 101 DECLARE q_curs CURSOR FOR SELECT * FROM orders WHERE customer_num = a LET a = 106 OPEN q_curs

In the next example, INFORMIX-4GL selects rows where the value in the customer_num column equals a[5]:
LET i = 5 DECLARE q_curs CURSOR FOR SELECT * FROM orders WHERE customer_num = a[i] LET i = 2 OPEN q_curs

19. You cannot DECLARE a cursor for an INSERT statement that contains an embedded SELECT statement. 20. If you DECLARE a cursor for an INSERT statement that has a VALUES clause containing only constants, INFORMIX-4GL does not create a buffer, but merely keeps count of the number of inserts. Such inserts are never ushed as the result of a PUT statement. Flushing occurs when you issue a FLUSH or CLOSE cursor statement. 21. The DECLARE statement for a cursor must physically appear before any statement that species the cursor. The cursor-name has meaning from the point at which you DECLARE it, to the end of the same source le. It is not a global identier that can be referenced in a separate source le. 22. You cannot specify a SCROLL INSERT cursor.

INFORMIX-4GL Statement Syntax

7-67

DECLARE

Examples
DECLARE scurs CURSOR FOR SELECT * FROM customer DECLARE wh_curs CURSOR WITH HOLD FOR st_1 DECLARE ucurs CURSOR FOR SELECT * FROM customer WHERE customer_num > 110 FOR UPDATE OF fname, lname DECLARE icurs CURSOR FOR INSERT INTO stock VALUES (stock_no, man_code, descr, u_price, unit, u_desc) DECLARE s_curs SCROLL CURSOR FOR SELECT * FROM orders WHERE customer_num = 104

Related Statements
CLOSE, DELETE, FETCH, FLUSH, FOREACH, FREE, OPEN, PREPARE, PUT, SELECT, UPDATE

7-68

INFORMIX-4GL Statement Syntax

DEFER

DEFER
Overview
Use the DEFER statement to keep INFORMIX-4GL from terminating your program whenever a user presses the Interrupt key (usually CTRL-C or DEL) or the QUIT key (usually CTRL-\).

Syntax
DEFER { INTERRUPT | QUIT }

Explanation
DEFER INTERRUPT QUIT

is a required keyword. is an optional keyword. is an optional keyword.

Notes
1. In the absence of the DEFER statement, your program will stop immediately whenever Interrupt or Quit is pressed. 2. The DEFER statement sets a global ag (int_ag for INTERRUPT and quit_ag for QUIT) to non-zero whenever the user presses the Interrupt or Quit key. The programmer must reset the ags to zero. 3. If the DEFER INTERRUPT statement has been executed and the user subsequently enters an Interrupt during an INPUT statement, program control will leave the INPUT statement and int_ag will be set. This applies to the CONSTRUCT, INPUT ARRAY, and PROMPT statements, as well. 4. The DEFER INTERRUPT statement can occur only once in a program, and then only in the MAIN program block. After being executed, it remains in effect for the duration of the program. This characteristic applies as well to the DEFER QUIT statement.

Example
DEFER INTERRUPT

INFORMIX-4GL Statement Syntax

7-69

DEFER

Related Statement
WHENEVER

7-70

INFORMIX-4GL Statement Syntax

DEFINE

DEFINE
Overview
Use the DEFINE statement to dene identiers in your program and to set aside adequate memory for each 4GL program variable.

Syntax
DEFINE variable-list { type | LIKE table.column | RECORD { LIKE table.* | variable-list [ , . . . ] END RECORD } } [ , . . . ]

Explanation
DEFINE

is a required keyword. is one or more identiers of program variable. is one of these data types (as dened in Chapter 2):
SMALLINT INTEGER INT DECIMAL [ (m [ , n ] ) ] DEC [ ( m [ , n ] ) ] NUMERIC [ (m [ , n ] ) ] SMALLFLOAT REAL RECORD [ LIKE table. * ] FLOAT [ ( n ) ] DOUBLE PRECISION [ ( n ) ] MONEY [ (m [ , n ] ) ] CHAR [ ( n ) ] CHARACTER [ ( n ) ] DATE DATETIME qualier INTERVAL qualier

variable-list type

ARRAY [ i , j , k ] OF type

LIKE

is a keyword to specify the data type indirectly. is the full identier for a column in the current database. The DATABASE statement must precede DEFINE statements that use indirect typing. is a data type that describes a set of variables of possibly differing database data types. is the name of a database table. are keywords that follow the declaration of the last element of a program record.
INFORMIX-4GL Statement Syntax 7-71

table.column

RECORD

table
END RECORD

DEFINE

Notes
1. Elements of records are addressed as record_name. column_name. 2. If the DEFINE statement is used in a function or MAIN program block, it must be the rst statement to appear in that function or MAIN program block. 3. See the Data Types section in Chapter 2 for a full discussion of 4GL data types for 4GL variables. 4. The section Language Conventions in Chapter 2 describes the identiers of 4GL variables and their scope of reference.

Example
DEFINE p_customer RECORD LIKE customer.*, p_orders RECORD order_num LIKE orders.order_num, order_date LIKE orders.order_date, po_num LIKE orders.po_num, ship_instruct LIKE orders.ship_instruct END RECORD, p_stock ARRAY[30] OF RECORD s_num LIKE stock.stock_num, m_code LIKE stock.manu_code END RECORD, stock_tot SMALLINT

Related Statements
GLOBALS, LET

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX -Online Programmers Manual for more information.

7-72

INFORMIX-4GL Statement Syntax

DELETE

DELETE
Overview
Use the DELETE statement to delete one or more rows from a table.

Syntax
DELETE FROM table-name [ WHERE { condition | CURRENT OF cursor-name } ]

Explanation
DELETE FROM are required keywords.

table-name
WHERE

is the name of the table from which you want to delete rows. is a keyword. is a condition of a standard WHERE clause. (See the SELECT statement for further information.) INFORMIX-4GL deletes all rows that satisfy the condition in the WHERE clause. are keywords. is the SQL identier of a previously DECLAREd and positioned cursor.

condition

CURRENT OF

cursor-name

Notes
1. When you create a database with transactions that is not MODE ANSI, each DELETE statement you execute is treated as a single transaction, even if you do not use the BEGIN WORK and COMMIT WORK or ROLLBACK WORK statements. 2. Each row affected by a DELETE statement within a transaction is locked for the duration of the transaction; therefore, a single DELETE statement that affects a large number of rows locks the rows until the entire operation is completed. If the number of rows affected is very large, you might exceed the limits that your operating system places on the maximum number of simultaneous locks. If you exceed these limits, you may want to either reduce the scope of the DELETE statement or lock the entire table before executing the statement. See the section Locking in Chapter 3 for a more detailed description of table-level and row-level locking in INFORMIX-4GL.
INFORMIX-4GL Statement Syntax 7-73

DELETE

3. To use the WHERE CURRENT OF option, you must have previously DECLAREd the cursor-name with the FOR UPDATE option. 4. If you use the CURRENT OF option, DELETE removes the row of the active set at the current position of the cursor. The cursor is left pointing between the remaining rows and you cannot use it for DELETE or UPDATE until you reposition it with a FETCH statement. 5. If your database has transactions and you use the WHERE CURRENT OF clause, you must execute the DELETE statement within a transaction.

Examples
DELETE FROM items WHERE order_num = onum DELETE FROM orders WHERE CURRENT OF query_cursor

These statements remove all items belonging to the order number set in the program variable onum from the items table and remove the row from the orders table pointed to by the cursor query_cursor.

Related Statements
DECLARE, INSERT, UPDATE

7-74

INFORMIX-4GL Statement Syntax

DISPLAY

DISPLAY
Overview
Use the DISPLAY statement to display data values on the screen.

Syntax
DISPLAY{ BY NAME variable-list | variable-list [ TO { eld-list | screen-record [ [ n ] ].* } [ , . . . ] | AT row, column ] } [ ATTRIBUTE ( attribute-list ) ]

Explanation
DISPLAY BY NAME

is a required keyword. are keywords instructing INFORMIX-4GL to match the names of variables with screen eld names. is a required list of one or more program variables and/or constants, separated by commas. is a keyword to specify that INFORMIX-4GL will display the variable_list in screen elds or in a screen array. is a list of one or more screen eld names in the current screen form. is the identier of a collection of eld names dened in a form specication as a SCREEN RECORD. is an integer, enclosed in brackets, to specify the row of a screen array (beginning with line 1) where the variable-list should be displayed. is a keyword to specify coordinates of a location on the screen or in the current window. is an integer variable or constant, indicating a row of the screen or current window. is an integer variable or constant, indicating a column of the screen or current window. is a keyword to specify screen display attributes. is a list (in parentheses) of one or more screen display attributes, separated by commas.

variable-list
TO

eld-list screen-record [n]

AT

row column
ATTRIBUTE

(attribute-list)

INFORMIX-4GL Statement Syntax

7-75

DISPLAY

Notes
1. The DISPLAY statement (without the BY NAME, TO, or AT keywords) displays variable-list on the next line. This can format displayed values with CLIPPED, USING, and COLUMN, but not with the ATTRIBUTE (attribute-list) clause. 2. Changing the data stored in program variables has no effect on the current screen display until this statement is executed again. 3. INFORMIX-4GL displays number values right justied, and character strings left justied in the screen eld. 4. If a character value does not t in the eld, its display is truncated. If a number value does not t in the eld, INFORMIX-4GL lls the eld with asterisks (*) to indicate an overow. 5. The DISPLAY BY NAME option selects screen elds, based on the identity of the program variable name and the eld name. INFORMIX-4GL uses only the sufx portion of these variable names and eld names. This option results in an error (setting status < 0) unless the sufxes are unique and unambiguous. 6. The DISPLAY TO screen-record [n].* option lists constants or program variables on the nth row of a screen array. You can move such values up or down with the SCROLL statement. 7. You can use the DISPLAY AT statement to display variable-list at a specied location on the screen or in the current window. You can use CLIPPED and USING to format displayed values. 8. The coordinates start with row 1 and column 1 in the upper left corner of the screen or current 4GL window. The row coordinates increase as you go down, and the column coordinates increase as you move from left to right. On a standard terminal screen, the lower right corner has the coordinates (24, 80). 9. An error occurs (setting status < 0 ) if either the row or column exceeds the dimensions of the screen or of the current window. 10. If you use the AT option when the last element of variable-list is a NULL CHAR value, INFORMIX-4GL clears to the end of the line. For example,
DISPLAY "" AT n,1

clears the nth line of the screen or of the current window. 11. If your program includes a DISPLAY statement followed by a DISPLAY AT statement, INFORMIX-4GL clears the screen or the current window before producing the second display.

7-76

INFORMIX-4GL Statement Syntax

DISPLAY

12. If no TO clause or AT clause species a location, a compile-time error occurs if you use the ATTRIBUTE clause. 13. In a DISPLAY TO statement, any screen attributes specied in attribute-list apply to all the elds in eld-list or screen-record. 14. If you use the ATTRIBUTE clause, none of the default attributes listed in syscolatt or in the form specication le for elds in eld-list or screen-record apply. The attribute-list temporarily overrides any attributes specied in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these elds. 15. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

You can specify zero or one of the keywords in the left-hand columns, and from zero to three from the right-hand column (but some terminals may not support some combinations). On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. Do not include the equal ( = ) sign, which in this table shows the effect on monochrome terminals of keywords that specify color. These keywords cannot produce the effects suggested by their names unless the termcap or terminfo les and the physical terminals support the attribute. (See Appendix I, Modifying termcap and terminfo.) Note: Some terminal entries in termcap or terminfo include the sg#1 or xmc#1 capabilities. On these terminals, the rst character of variable-list is replaced by a blank if you use the DISPLAY AT statement with any display attribute. To be safe, make sure that the rst character of the variable-list is a blank if you specify any display attributes. 16. On UNIX systems that use terminfo les rather than termcap, INFORMIX-4GL does not support attributes that specify colors, and the only valid attribute-list keywords are REVERSE and UNDERLINE.

INFORMIX-4GL Statement Syntax

7-77

DISPLAY

Examples
DISPLAY BY NAME lname, fname DISPLAY "There are ", num USING "-####", " items in the list" AT 12,1 ATTRIBUTE(REVERSE, BLUE) DISPLAY add_cust.* TO sc_addr[4].*

Related Statements
INPUT, DISPLAY ARRAY, DISPLAY FORM, OPEN WINDOW

7-78

INFORMIX-4GL Statement Syntax

DISPLAY ARRAY

DISPLAY ARRAY
Overview
Use the DISPLAY ARRAY statement to display a program array in a screen array, and to permit scrolling through the array.

Syntax
DISPLAY ARRAY record-array TO screen-array.* [ ATTRIBUTE ( attribute-list ) ] { ON KEY ( key-list ) statement ... [ EXIT DISPLAY ] ... END DISPLAY | [ END DISPLAY ] }

Explanation
DISPLAY ARRAY

are required keywords. is a program array name. Usually, record-array is an array of records. is a required keyword. is the name of a screen record, dened in a form specication le, that corresponds to the elds in a row of a screen array. is an optional keyword. is a list of one or more screen-display attributes. are optional keywords. is usually a list of one or more function or CTRL key designations. It can also include ESC (if you have specied another key as the Accept key in the OPTIONS statement) or INTERRUPT (if you have executed a DEFER INTERRUPT statement). is an INFORMIX-4GL statement. is a statement that causes INFORMIX-4GL to exit from the DISPLAY ARRAY statement. is a statement that terminates a DISPLAY ARRAY statement. It is required only when an ON KEY clause is used,
INFORMIX-4GL Statement Syntax 7-79

record-array
TO

screen-array

ATTRIBUTE

attribute-list
ON KEY

key-list

statement
EXIT DISPLAY END DISPLAY

DISPLAY ARRAY

or when the DISPLAY ARRAY statement appears as the last statement in a clause and is followed by an ON KEY clause.

Notes
1. You must call set_count() with the number of lled rows in record-array prior to executing DISPLAY ARRAY. 2. The user can use the [ ] key to move the cursor down one row at a time and to scroll to the bottom of the screen array; the [ ] key to move the cursor up one row at a time and to scroll to the top of the screen array; [ F3 ] to scroll to the next page; and [ F4 ] to scroll to the previous page. You can use the OPTIONS statement to assign these functions to other keys. In addition, you must dene the key assignments properly in the termcap or terminfo les. 3. The user can exit from the DISPLAY ARRAY statement by pressing ESC, or by pressing the key specied as the ACCEPT KEY in the OPTIONS statement. The program should tell the user to do this. 4. The following conditions require that an END DISPLAY statement appear in your program:

The DISPLAY ARRAY statement includes one or more ON KEY clauses. The DISPLAY ARRAY statement appears as the last statement in a
clause (within an INPUT statement, for example) and is followed by an
ON KEY clause.

5. By default, INFORMIX-4GL displays number variables right-justied and character variables left-justied in the screen eld. 6. If a displayed character value is larger than the eld, INFORMIX-4GL truncates the value. If a displayed number value is larger than the eld, INFORMIX-4GL lls the eld with asterisks (*). 7. The attributes listed in attribute-list apply to all the elds in screen-array. 8. If you use the ATTRIBUTE clause, none of the default attributes listed in syscolatt or in the form specication le for the elds in screen-array will apply.

7-80

INFORMIX-4GL Statement Syntax

DISPLAY ARRAY

9. The following list shows the screen attributes allowed in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

On color terminals, NORMAL is interpreted as WHITE; BOLD as RED; DIM as BLUE; and INVISIBLE as BLACK. If you have a colornames le, you can use the color names listed there. 10. INFORMIX-4GL passes control to the statements following an ON KEY clause when the user presses a key in key-list. After executing the statements in the ON KEY clause, INFORMIX-4GL resumes the display with the cursor in the same location as before the ON KEY break, unless NEXT FIELD and EXIT DISPLAY are implemented. 11. The notation for function keys is F1, F2, F3, . . . F36 . The notation for CTRL keys is CONTROL-key where key is any letter except A, D, H, L, R, or X. The notation for is ESC or ESCAPE. The notation for the Interrupt key is INTERRUPT. 12. By default, both ESCAPE and INTERRUPT are exits from the DISPLAY ARRAY statement. If the DEFER INTERRUPT statement has been executed, an INTERRUPT causes INFORMIX-4GL to set int_ag to non-zero, and terminates the DISPLAY ARRAY statement (unless the Interrupt key has been redened in an ON KEY clause). Otherwise, an Interrupt causes an immediate program stop. 13. You can include the following keys in a key-list under the stated conditions:

ESCAPE, if you have specied another key as the Accept key in the OPTIONS statement.

[ F3 ], if you have specied another key as the Next key in the OPTIONS
statement.

[ F4 ], if you have specied another key as the Previous key in the

OPTIONS statement.

The Interrupt key, if you have executed a DEFER INTERRUPT statement. (When the user presses the Interrupt key under these conditions, INFORMIX-4GL executes the statements in the ON KEY

INFORMIX-4GL Statement Syntax

7-81

DISPLAY ARRAY

clause and sets int_ag to non-zero but does not terminate the DISPLAY ARRAY statement.) Do not use the following keys in a key-list:

CTRL-A, CTRL-D, CTRL-H, CTRL-L, CTRL-R, or CTRL-X since these CTRL keys are reserved for editing functions in the CONSTRUCT, INPUT, and INPUT ARRAY statements.

Other keys that have special meaning for your operating system.
14. Do not execute PROMPT, INPUT, or INPUT ARRAY statements within the ON KEY clause of a DISPLAY ARRAY statement. You can, however, call a function that executes one of these statements.

Examples
DISPLAY ARRAY pa_array TO sc_array.* DISPLAY ARRAY p_items TO s_items.* ON KEY (CONTROL-E) MESSAGE "Highlight an item and ", "press the ACCEPT key." END DISPLAY INPUT BY NAME p_customer.* AFTER FIELD company ... DISPLAY ARRAY pa_array TO sc_array.* END DISPLAY ON KEY (CONTROL-B) ... END INPUT

Related Statements
DISPLAY, SCROLL

7-82

INFORMIX-4GL Statement Syntax

DISPLAY FORM

DISPLAY FORM
Overview
Use the DISPLAY FORM statement to display a pre-compiled screen form.

Syntax
DISPLAY FORM form-name [ ATTRIBUTE ( attribute-list ) ]

Explanation
DISPLAY FORM are required keywords.

form-name
ATTRIBUTE

is an INFORMIX-4GL identier that has been associated with a screen form in an OPEN FORM statement. is an optional keyword. is a list of one or more screen attributes that will apply to the delimiters of the screen form, and to any text outside display elds.

attribute-list

Notes
1. DISPLAY FORM displays the screen form starting on the third line of the terminal screen or window. You can change the starting line for all windows (including the screen) by using the OPTIONS statement or for a specic window by using an ATTRIBUTE clause in the appropriate OPEN WINDOW statement. 2. The following list shows the screen attributes allowed in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. If you have a colornames le, you can use the color names listed there. (See Appendix I.)
INFORMIX-4GL Statement Syntax 7-83

DISPLAY FORM

3. INFORMIX-4GL issues an error if a window is not large enough to display a form. See Chapter 13 of the INFORMIX-4GL User Guide and the OPEN WINDOW statement in this chapter for more information about displaying a form in a window. 4. The DISPLAY FORM statement is not required if you opened and displayed a form using the WITH FORM option of the OPEN WINDOW statement.

Examples
DISPLAY FORM order_entry DISPLAY FORM inventory ATTRIBUTE(BLUE)

Related Statements
CLEAR, CLOSE FORM, OPEN FORM, OPEN WINDOW

7-84

INFORMIX-4GL Statement Syntax

DROP AUDIT

DROP AUDIT
Overview
Use the DROP AUDIT statement to delete an audit trail le.

Syntax
DROP AUDIT FOR table-name

Explanation
DROP AUDIT FOR

are required keywords. is the name of the table whose audit trail le you want to delete.

table-name

Notes
1. Us e the DROP AUDIT statement to remove the old audit trail le when you have made a backup of your database les. Use the CREATE AUDIT statement to start a new audit trail and then back up the table. See the section Audit Trails in Chapter 3 for more information. 2. You must own table-name or have DBA status to use the DROP AUDIT statement.

Example
DROP AUDIT FOR orders

Related Statements
CREATE AUDIT, RECOVER TABLE

INFORMIX-4GL Statement Syntax

7-85

DROP DATABASE

DROP DATABASE
Overview
Use the DROP DATABASE statement to delete an entire database, including all system catalogs, indexes, data, and the transaction log.

Syntax
DROP DATABASE { database-name | char-variable }

Explanation
DROP DATABASE

are required keywords. is the name of the database you want to delete. is a program variable of type CHAR containing the name of the database you want to delete.

database-name char-variable

Notes
1. You must own all the tables in the database or have DBA status to run the DROP DATABASE statement. 2. The DROP DATABASE statement does not delete the database directory if there are any les in the database directory other than those created for database tables and their indexes. 3. You cannot drop the current database. You must execute the CLOSE DATABASE statement rst. 4. The DROP DATABASE statement cannot be rolled back. 5. For databases with transactions, the DROP DATABASE statement deletes the transaction log. 6. The DROP DATABASE statement cannot appear in a multi-statement PREPARE.

Example
DROP DATABASE stores

7-86

INFORMIX-4GL Statement Syntax

DROP DATABASE

Related Statements
CREATE DATABASE, CLOSE DATABASE

INFORMIX-4GL Statement Syntax

7-87

DROP INDEX

DROP INDEX
Overview
Use the DROP INDEX statement to delete an index.

Syntax
DROP INDEX index-name

Explanation
DROP INDEX

are required keywords. is the name of the index you want to delete.

index-name

Notes
1. You must own the index or have DBA privilege to use the DROP INDEX statement. 2. You cannot roll back the DROP INDEX statement. 3. You cannot drop the index created when a column or composite column list is identied as having a UNIQUE CONSTRAINT in the CREATE TABLE statement.

Example
DROP INDEX i_ordnum

Related Statement
CREATE INDEX

7-88

INFORMIX-4GL Statement Syntax

DROP SYNONYM

DROP SYNONYM
Overview
Use the DROP SYNONYM statement to delete a previously dened synonym for a table or view.

Syntax
DROP SYNONYM synonym

Explanation
DROP SYNONYM are required keywords.

synonym

is a 4GL identier.

Notes
1. You must be the owner of the synonym or have DBA status to use the DROP SYNONYM statement. 2. When you compile a program containing a synonym, the synonym is replaced in the compiled program by the real identier of the table or view (as listed in the systables system catalog). If you subsequently drop the synonym, the compiled program will still run. 3. The DROP SYNONYM statement cannot be rolled back.

Example
DROP SYNONYM cust

Related Statement
CREATE SYNONYM

INFORMIX-4GL Statement Syntax

7-89

DROP TABLE

DROP TABLE
Overview
Use the DROP TABLE statement to delete a table, along with its associated indexes and data.

Syntax
DROP TABLE table-name

Explanation
DROP TABLE

are required keywords. is the name of the table you want to delete.

table-name

Notes
1. When you delete a table, you also delete the data stored in it, the indexes on columns, any synonyms assigned to it, and any authorizations you have granted on the table. You also delete all views based on the table. 2. You cannot drop any of the system catalog tables. 3. You must be the owner of a table or have DBA privilege to use the DROP TABLE statement. 4. The DROP TABLE statement cannot be rolled back.

Example
DROP TABLE customer

Related Statement
CREATE TABLE

7-90

INFORMIX-4GL Statement Syntax

DROP VIEW

DROP VIEW
Overview
Use the DROP VIEW statement to delete a view from the database.

Syntax
DROP VIEW view-name

Explanation
DROP VIEW

are required keywords. is the identier of a view.

view-name

Notes
1. You must be the owner of the view or have DBA status to use the DROP VIEW statement. 2. When you drop view-name, you also drop all views that have been dened in terms of view-name. 3. You cannot roll back the DROP VIEW statement. 4. See the section Views in Chapter 3 for more information.

Example
DROP VIEW cust1

Related Statements
CREATE VIEW, DROP TABLE

INFORMIX-4GL Statement Syntax

7-91

ERROR

ERROR
Overview
Use the ERROR statement to display an error message on the Error line (by default, the bottom line of the screen), and to ring the terminal bell.

Syntax
ERROR display-list [ ATTRIBUTE ( attribute-list ) ]

Explanation
ERROR

is a required keyword. is a list of one or more program variables and/or string constants (enclosed in quotation marks), separated by commas. is an optional keyword. is a list of one or more screen attributes, separated by commas.

display-list
ATTRIBUTE

attribute-list

Notes
1. The string generated by substituting values for the variables in display-list must t on a single display line. The string is displayed in a window on the Error line. 2. You can change the position of the Error line with the OPTIONS statement. The location of the Error line is relative to the screen, rather than to the current window. 3. The display-list can contain the CLIPPED and USING functions. 4. REVERSE is the default attribute for the ERROR display. You can alter the default attribute with the ATTRIBUTE clause.

7-92

INFORMIX-4GL Statement Syntax

ERROR

5. The following list shows the screen attributes allowed in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. If you have a colornames le, you can use the color names listed there. (See Appendix I.)

Example
ERROR "There is no match for ", pattern

Related Statements
DISPLAY, MESSAGE, OPTIONS

INFORMIX-4GL Statement Syntax

7-93

EXECUTE

EXECUTE
Overview
Use the EXECUTE statement to run a statement specied by a previous PREPARE statement.

Syntax
EXECUTE statement-id [ USING input-list ]

Explanation
EXECUTE

is a required keyword. is an SQL statement identier that you named in a previous PREPARE statement. is an optional keyword. is a list of program variables to be substituted as values for the question marks (?) in the statement indicated by statement-id. Use this option when you know the number and data types of the values that the PREPAREd statement requires.

statement-id
USING

input-list

Notes
1. After you PREPARE an SQL statement, you can EXECUTE it as often as you desire. 2. To use the USING clause, you must know the number of the parameters of the PREPAREd statement. The data type of each variable in input-list must be compatible with the value expected in the PREPAREd statement for the corresponding parameter. 3. You cannot EXECUTE a PREPAREd SELECT statement. You must use DECLARE with a FOREACH loop, or use the OPEN, FETCH, and CLOSE statements to execute a statement-id that references a SELECT statement. 4. You cannot EXECUTE a PREPAREd INSERT statement that uses a cursor. You must use DECLARE with a FOREACH loop, or else use the OPEN, PUT, and CLOSE statements to execute INSERT statements that you want to process as a group.

7-94

INFORMIX-4GL Statement Syntax

EXECUTE

5. The scope of reference of the statement-id is from the PREPARE statement that names it until the end of its source-code module. The EXECUTE statement cannot reference a statement-id that you PREPARE in a different module, or later in the same module. 6. PREPAREd statements require database engine resources that are not unlimited. If you specify FREE statement-id to release engine resources, you cannot subsequently EXECUTE that statement unless you PREPARE it again.

Example
LET s1 = "UPDATE orders SET po_num = ?, order_date = ?" PREPARE statement_1 FROM s1 EXECUTE statement_1 USING purchase_num, order_date

Related Statements
DECLARE, FREE, PREPARE

INFORMIX-4GL Statement Syntax

7-95

EXIT

EXIT
Overview
Use the EXIT statement to terminate the program; to break out of a FOR, a FOREACH, or a WHILE loop; to leave the CASE statement; to leave the INPUT or INPUT ARRAY statement; or to leave a menu.

Syntax
EXIT { CASE | DISPLAY | FOR | FOREACH | INPUT | MENU | PROGRAM [ ( integer-expr ) ] | WHILE }

Explanation
EXIT CASE DISPLAY FOR FOREACH INPUT MENU PROGRAM

is a required keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an expression that evaluates as an integer. is an optional keyword.

integer-expr
WHILE

Notes
1. You can use the CASE option only within a CASE statement, the DISPLAY option only within a DISPLAY ARRAY statement, the FOR option only within a FOR statement, the FOREACH option only within a FOREACH statement, the INPUT option only within an INPUT or INPUT ARRAY statement, the MENU option only following a COMMAND clause of a MENU statement, and the WHILE option only within a WHILE statement. In each case, program control passes to the rst statement following the END CASE, END DISPLAY, END FOR, END FOREACH, END INPUT, END MENU, or END WHILE statements, respectively.

7-96

INFORMIX-4GL Statement Syntax

EXIT

2. You can use the PROGRAM option anywhere; it immediately terminates the program. 3. Use the optional integer argument of EXIT PROGRAM to return a status code to the operating system upon program termination.

Related Statement
CONTINUE

INFORMIX-4GL Statement Syntax

7-97

FETCH

FETCH
Overview
Use the FETCH statement to move the cursor to a new row in the active set and to retrieve the values from that row.

Syntax
FETCH [ NEXT | { PREVIOUS | PRIOR } | FIRST | LAST | CURRENT | RELATIVE m | ABSOLUTE n ] cursor-name [ INTO variable-list ]

Explanation
FETCH NEXT PREVIOUS PRIOR FIRST LAST CURRENT RELATIVE m

is a required keyword. is a keyword indicating the next row in the active list. NEXT is the default. is a keyword indicating the prior row in the active list. is a keyword that is synonymous with PREVIOUS. is a keyword indicating the rst row of the active list. is a keyword indicating the last row of the active list. is a keyword indicating the current row of the active list. is a keyword indicating the mth row relative to the current cursor position in the active list. Here m can be either an integer or a program variable and can be either positive or negative. is a keyword indicating the nth row in the active list. Here n can be either an integer or a program variable. is a 4GL identier that you specied in a previous DECLARE statement. You must also OPEN cursor-name. is an optional keyword. is a list of 4GL program variables that contains the column values of the row pointed to by cursor-name.

ABSOLUTE n

cursor-name
INTO

variable-list

7-98

INFORMIX-4GL Statement Syntax

FETCH

Notes
1. FETCH NEXT is the default condition. 2. You must DECLARE a SCROLL cursor before issuing a FETCH statement that includes the PRIOR, PREVIOUS, FIRST, LAST, CURRENT, RELATIVE m, or ABSOLUTE n keywords. 3. If the SELECT statement associated with the cursor has an INTO clause, there must be no INTO clause in any FETCH statement referring to that cursor. If the SELECT statement has no INTO clause, the FETCH statement must have one. 4. You can FETCH into a program array element only by using an INTO clause in the FETCH statement. Do not refer to an array element in the SELECT-statement of a DECLARE statement. 5. Under any of the following circumstances, INFORMIX-4GL returns a row not found code (status = NOTFOUND ).

You issue a FETCH NEXT statement when the cursor points to the last
row in the active set.

You issue a FETCH PRIOR or FETCH PREVIOUS statement when the

cursor points to the rst row in the active set.

You issue a FETCH ABSOLUTE n statement when no nth row exists in

the active set.

You issue a FETCH RELATIVE m statement when no mth row exists in

the active set. You can use the WHENEVER NOT FOUND statement to specify an action to take if status = NOTFOUND. 6. FETCH does not lock a row unless the DECLARE statement contains a SELECT with a FOR UPDATE clause. It is possible to retrieve a row that is being UPDATEd or DELETEd by a concurrent process. 7. If the cursor was DECLAREd FOR UPDATE and the current database is not MODE ANSI but uses explicit transactions, you can include FETCH only within a transaction (that is, following a BEGIN WORK statement). In a MODE ANSI database, all operations take place inside a transaction, so a FETCH can be done at any time while cursor-name is OPEN.

INFORMIX-4GL Statement Syntax

7-99

FETCH

Examples
FETCH query_curs INTO cnum, lname FETCH PREVIOUS q_curs INTO orders.* FETCH LAST q_curs INTO orders.* FETCH ABSOLUTE 8 q_curs INTO orders.* FETCH RELATIVE -10 q_curs INTO orders.*

Related Statements
CLOSE, DECLARE, DELETE, FOREACH, OPEN, PREPARE, PUT, SELECT, UPDATE, WHENEVER

7-100

INFORMIX-4GL Statement Syntax

FINISH REPORT

FINISH REPORT
Overview
Use the FINISH REPORT statement to cause INFORMIX-4GL to nish processing a report.

Syntax
FINISH REPORT report-name

Explanation
FINISH REPORT

are required keywords. is the identier of a report.

report-name

Note
You must use the FINISH REPORT statement to let INFORMIX-4GL know that no more statements are to be included in the report processing.

Example
FINISH REPORT cust_ords

Related Statements
OUTPUT TO REPORT, START REPORT

INFORMIX-4GL Statement Syntax

7-101

FLUSH

FLUSH
Overview
Use the FLUSH statement to force INFORMIX-4GL to insert the buffered rows into the database without closing the cursor.

Syntax
FLUSH cursor-name

Explanation
FLUSH

is a required keyword. is the name of a cursor that has been DECLAREd for an INSERT statement.

cursor-name

Notes
1. The global variables status (whose value is taken from SQLCA.SQLCODE) and SQLCA.SQLERRD[3] indicate the result of each FLUSH statement. If INFORMIX-4GL successfully inserts all the buffered rows into the database, it sets status to zero and sets SQLCA.SQLERRD[3] to the number of rows inserted. If INFORMIX-4GL is unsuccessful in its attempt to insert the rows into the database, it sets status to a negative number (specically, the number of the error message) and sets SQLCA.SQLERRD[3] to the number of rows successfully inserted into the database. 2. You can use the FLUSH statement to force the insertion. You cannot delay insertion by not using the FLUSH statement. INFORMIX-4GL automatically ushes the buffer when it is full. 3. Insert cursors that contain only constants in the values clause are not buffered. INFORMIX-4GL keeps a count of the number of rows to be inserted into the database, and the database is updated only when you issue a FLUSH or CLOSE statement. 4. If you exit a program without closing the cursor, the buffer is left unushed. Rows inserted into the buffer and remaining since the last ush are lost. Do not expect the end of program to close the cursor and ush the buffer.

7-102

INFORMIX-4GL Statement Syntax

FLUSH

Example
FLUSH icurs

Related Statements
CLOSE, DECLARE, OPEN, PUT

INFORMIX-4GL Statement Syntax

7-103

FOR

FOR
Overview
Use the FOR statement to cause a sequence of statements to be executed a specied number of times.

Syntax
FOR integer-var = integer-expr TO integer-expr [STEP integer-expr] statement ... [CONTINUE FOR] ... [EXIT FOR] ... END FOR

Explanation
FOR

is a required keyword. is a program variable of type INTEGER or SMALLINT that serves as a counter. is an expression that evaluates to an INTEGER or a SMALLINT.

integer-var integer-expr
TO STEP

is a required keyword. is an optional keyword. is an INFORMIX-4GL statement. is an optional statement. is an optional statement. are required keywords.

statement
CONTINUE FOR EXIT FOR END FOR

7-104

INFORMIX-4GL Statement Syntax

FOR

Notes
1. The FOR statement repeats the sequence of statements up to the END FOR as integer-var takes on the values of the rst integer-expr TO the second integer-expr in STEPs of the third integer-expr. The default STEP is 1. 2. The CONTINUE FOR statement interrupts the sequence and causes the program control to return to the top of the sequence and to increment and test the counter integer-var. 3. The EXIT FOR statement interrupts the sequence and causes the program control to jump to the rst statement following the END FOR keywords. 4. If integer-var is greater than the TO integer-expr upon entry and the STEP value is positive, none of the statements up to END FOR is executed. 5. The STEP value may be negative.

Example
DEFINE order_total MONEY(8), i INTEGER LET order_total = 0.00 FOR i = 1 TO ARR_COUNT() LET order_total = order_total + p_items[i].total_price END FOR

Related Statements
CONTINUE, EXIT, FOREACH, WHILE

INFORMIX-4GL Statement Syntax

7-105

FOREACH

FOREACH
Overview
Use the FOREACH statement to cause a sequence of statements to be executed for each row returned from a query.

Syntax
FOREACH cursor-name [INTO variable-list] statement ... [CONTINUE FOREACH] ... [EXIT FOREACH] ... END FOREACH

Explanation
FOREACH

is a required keyword. is the name of a cursor that previously was DECLAREd. is an optional keyword. is a list of one or more program variables, separated by commas. is an optional statement. is an optional statement. are required keywords.

cursor-name
INTO

variable-list
CONTINUE FOREACH EXIT FOREACH END FOREACH

7-106

INFORMIX-4GL Statement Syntax

FOREACH

Notes
1. The FOREACH statement repeats the sequence of statements up to END FOREACH for each row returned by the query associated with cursorname. The FOREACH statement OPENs the cursor and performs successive FETCHes until the active list of the cursor is exhausted. 2. The INTO clause is required only if there is no INTO clause in the SELECT statement associated with cursor-name, and vice versa. It lists the variables into which INFORMIX-4GL places the values returned by the query. 3. When FETCHing into a program array, you must place the INTO clause on the FOREACH statement and not on the SELECT-statement of a DECLARE statement. 4. The CONTINUE FOREACH statement interrupts the sequence and causes program control to return to the top of the sequence and to FETCH the next row of the query. 5. The EXIT FOREACH statement interrupts the sequence and causes program control to jump to the rst statement following the END FOREACH keywords. 6. If the query returns no rows, none of the statements up to the END FOREACH is executed, and program control passes immediately to the rst statement following END FOREACH. If you need to know whether any rows were returned, you can set up a ag or a counter as in the example that follows these notes. 7. The FOREACH statement performs an implied OPEN statement. You cannot use the FOREACH statement if the OPEN statement must have a USING clause to dene unknown parameters in the SELECT statement. 8. If your database has transactions, the FOREACH statement must appear inside a transaction. 9. If, within the FOREACH statement, the WHENEVER NOT FOUND statement evaluates to TRUE, the open cursor is automatically closed.

INFORMIX-4GL Statement Syntax

7-107

FOREACH

Example
PROMPT "Enter cut-off date for query: " FOR o_date DECLARE q_curs CURSOR FOR SELECT order_num, o.customer_num, company FROM orders o, customer c WHERE o.customer_num = c.customer_num AND order_date < o_date LET counter = 0 FOREACH q_curs INTO ord_num, cust_num, comp LET counter = counter + 1 CALL scan(ord_num, cust_num, comp) END FOREACH IF counter = 0 THEN ERROR "No orders before ", o_date END IF

Related Statements
CONTINUE, EXIT, FETCH, FOR, OPEN, WHILE, WHENEVER

7-108

INFORMIX-4GL Statement Syntax

FREE ( O )

FREE ( O )
Overview
The FREE statement releases database engine resources allocated to a PREPAREd statement or to an OPENed and CLOSEd cursor.

Syntax
FREE { statement-id | cursor-name }

Explanation
FREE

is a required keyword. is the name of a statement that has been PREPAREd. is the name of a cursor whose DECLARE statement includes the keywords SELECT or INSERT.

statement-id cursor-name

Notes
1. After you FREE statement-id, a cursor or EXECUTE statement cannot use it until you PREPARE it again. 2. If cursor-name is DECLAREd FOR SELECT or FOR INSERT, a statement is automatically PREPAREd when you OPEN the cursor. The statement has no programmer-assigned statement-id. To release engine resources from that statement, use FREE cursor-name. Afterward, you cannot use the cursor unless you OPEN it again. 3. Do not FREE a cursor-name that was DECLAREd FOR statement-id. Use instead FREE statement-id.

Examples
FREE query_2 FREE scurs

INFORMIX-4GL Statement Syntax

7-109

FUNCTION

FUNCTION
Overview
Use the FUNCTION statement to dene a function.

Syntax
FUNCTION function-name ( [ argument-list ] ) statement ... [ RETURN expr-list ] ... END FUNCTION

Explanation
FUNCTION

is a required keyword. is a program identier for the name of the function. is a list (enclosed in parentheses) of one or more variables, separated by commas. is an INFORMIX-4GL statement. is an optional keyword that causes program control to return to the calling program. is a list of zero or more expressions that yield the values returned by function-name. are required keywords that terminate the FUNCTION statement.

function-name (argument-list) statement

RETURN

expr-list
END FUNCTION

Notes
1. All arguments are passed by value. 2. You must DEFINE the arguments to the function, as well as other variables used locally within the function.

7-110

INFORMIX-4GL Statement Syntax

FUNCTION

3. When passing an entire record as an argument to a function, use the .* notation. In the FUNCTION statement, however, use only a record name that you dene within the FUNCTION routine. Thus you call the following function with the notation:
CALL example(orders.*) . . . FUNCTION example(r) DEFINE r RECORD LIKE orders.* ... END FUNCTION

4. Variables DEFINEd within a function are local to the function. 5. If function-name returns a single value, it may be used in an expression in place of a variable. Otherwise, it must be CALLed. 6. The number and data type of expressions in expr-list must be the same, and in the same order, as the number and type of program variables in the RETURNING clause of the CALL statement that calls the function. 7. The function-name must conform to the rules for 4GL identiers, as described in Chapter 2. An error results if function-name is the same as the identier of a global variable or of another function in the same program.

Related Statement
CALL

INFORMIX-4GL Statement Syntax 7-111

GLOBALS

GLOBALS
Overview
Use the GLOBALS statement to DEFINE one or more variables to be global variables or to refer to the le where global variables are DEFINEd.

Syntax
GLOBALS {lename | DEFINE-statement ... END GLOBALS}

Explanation
GLOBALS

is a required keyword. is the pathname of the le where the global variables are dened. is a DEFINE statement for the global variable. are required keywords that terminate the GLOBALS statement when variables are DEFINEd.

lename
DEFINE-statement END GLOBALS

Notes
1. You may have at most one GLOBALS statement where global variables are dened. This statement may be in a separate le or in the le containing the MAIN program block. 2. The GLOBALS lename statement must occur earlier in every le than any function that makes reference to a global variable. 3. The GLOBALS statement must lie outside the MAIN program block and any FUNCTION or REPORT routines. 4. If any global variable is DEFINEd LIKE a database column, the DATABASE statement naming the database must precede the GLOBALS statement.

7-112

INFORMIX-4GL Statement Syntax

GLOBALS

Examples
DATABASE stores GLOBALS DEFINE p_customer RECORD LIKE customer.* ... END GLOBALS GLOBALS "d4_globals.4gl"

Related Statement
DEFINE

INFORMIX-4GL Statement Syntax

7-113

GOTO

GOTO
Overview
Use the GOTO statement to transfer program control unconditionally to a designated point.

Syntax
GOTO [ : ]label-id

Explanation
GOTO

is a required keyword. is an optional prex to label-id and conforms to the ANSI standard for SQL syntax. is a 4GL identier.

: label-id

Notes
1. After a GOTO label-id statement successfully executes, program control is transferred to the statement that follows LABEL label-id:. See the syntax of the LABEL statement later in this chapter. 2. The label-id must be in the FUNCTION, REPORT, or MAIN routine in which the GOTO statement is used. You cannot transfer into or out of a FUNCTION or a REPORT with a GOTO statement.

Related Statements
LABEL, WHENEVER

7-114

INFORMIX-4GL Statement Syntax

GRANT

GRANT
Overview
Use the GRANT statement to specify user access privileges to a database or to the tables and views in a database.

Syntax
GRANT tab-privilege ON table-name TO { PUBLIC | user-list } [ WITH GRANT OPTION ] [ AS grantor ] GRANT db-privilege TO { PUBLIC | user-list }

Explanation
GRANT

is a required keyword. is one or more of the following table-level access types (multiple privileges must be separated by commas):
ALTER DELETE INDEX INSERT

tab-privilege

Add or delete columns or modify data types of columns. Delete rows. Create indexes. Insert rows.

SELECT [(cols)] Retrieve data from specied columns. UPDATE [(cols)] Change values in specied columns. ALL of the above access types. [ PRIVILEGES ] SELECT and UPDATE take column names as

arguments, allowing you to specify columns that the user may select or update. Separate column names with commas. The keyword PRIVILEGES following ALL is optional.
ON

is a required keyword. is the name of the table or view for which you are granting access privileges. is a required keyword.
INFORMIX-4GL Statement Syntax 7-115

table-name
TO

GRANT

PUBLIC

is the keyword that you use to specify access privileges for all users. is a list of login names for the users to whom you are granting access privileges. You can enter one login name or a series of login names, separated by commas. are optional keywords. is an optional keyword. is the username of the user issuing the GRANT statement. is one of the following database-level access types:
CONNECT

user-list

WITH GRANT OPTION AS

grantor db-privilege

Allows access to database tables without permission to create permanent tables and indexes. Allows access to database tables with permission to create permanent tables and indexes. Allows full database administrator privileges.

RESOURCE DBA

Notes
1. Database-level permissions (CONNECT, RESOURCE, and DBA) control access to the database. Table-level permissions (ALTER, DELETE, INDEX, INSERT, SELECT, UPDATE, and ALL) control access to a table. 2. With CONNECT privilege, you can create views and temporary tables. (The table-level SELECT privilege is required, however, on all columns from which the view is derived.) 3. The RESOURCE privilege includes the CONNECT privilege and adds the permission to create tables and indexes. 4. The DBA privilege includes the following:

The RESOURCE privilege Permission to drop, start, and roll forward the database. User INFORMIX also has permission to alter the system catalogs.

Permission to grant and revoke CONNECT, RESOURCE, and DBA privileges to and from other users. 5. When you create a database, you are the Database Administrator and have DBA privileges. 6. A DBA can use the AS keyword to grant table-level privileges on behalf of another user.
7-116 INFORMIX-4GL Statement Syntax

GRANT

7. You can grant privileges only on tables or views that you create, or on tables or views for which you have been given the GRANT OPTION. 8. When you use the WITH GRANT OPTION phrase to GRANT table-level privileges to another user, you give that user the power to GRANT the same privileges to another user. 9. If you do not specify one or more column names, the SELECT or UPDATE access that you grant applies to all columns. 10. You cannot roll back the GRANT statement. 11. The most restrictive privileges always take precedence. For example, if you grant RESOURCE privileges to a user but do not grant INDEX privileges at the table level, that user is not able to create indexes for that table. 12. You can grant DELETE, INSERT, or UPDATE privileges only on a simple view. You can grant SELECT privilege on a simple or complex view.

Examples
The following statements grant all table-level privileges (except ALTER) to all users who have CONNECT privileges to the database:
GRANT ALL ON customer TO PUBLIC REVOKE ALTER ON customer FROM PUBLIC

When you create a table in a database that is not MODE ANSI, all table-level privileges except ALTER are automatically granted to all users (PUBLIC). To restrict access privileges at the table level, you must revoke all privileges and grant those that you want:
REVOKE ALL ON customer FROM PUBLIC GRANT ALL ON customer TO joe, mary GRANT SELECT (fname, lname, company, city) ON customer TO PUBLIC

In a database created as MODE ANSI, no default table-level privileges exist. You must explicitly grant these privileges.

Related Statement
REVOKE

INFORMIX-4GL Statement Syntax

7-117

IF

IF
Overview
Use the IF statement to execute one or more statements conditionally.

Syntax
IF Boolean-expr THEN statement ... [ ELSE statement ... ] END IF

Explanation
IF

is a required keyword. is an expression that can be TRUE or FALSE. is a required keyword. is any INFORMIX-4GL statement, including another IF statement. is an optional keyword. are required keywords.

Boolean-expr
THEN

statement
ELSE END IF

Notes
1. If Boolean-expr is true, the statements following THEN down to an optional ELSE (if present) or to END IF (if there is no ELSE) are executed. 2. If Boolean-expr is false, the statements following THEN down to an optional ELSE (if present) or to END IF (if there is no ELSE) are skipped. If an ELSE is present, the statements following the ELSE are executed. 3. If Bool-expr evaluates as UNKNOWN because the expression contains NULL values, the IF statement behaves as though it were FALSE.

7-118

INFORMIX-4GL Statement Syntax

IF

Example
IF p_index <= 1 THEN ERROR "No more stock items in this direction" ELSE LET p_index = p_index - 1 DISPLAY dp_stock[p_index].* TO s_stock.* END IF

Related Statements
CASE, WHENEVER

INFORMIX-4GL Statement Syntax

7-119

INITIALIZE

INITIALIZE
Overview
Use the INITIALIZE statement to initialize a program variable.

Syntax
INITIALIZE variable-list { LIKE column-list | TO NULL }

Explanation
INITIALIZE

is a required keyword. is a list of one or more variables, separated by commas. is an optional keyword. is a list of column names, preceded by table names and separated by commas. are optional keywords to assign NULL values.

variable-list
LIKE

column-list
TO NULL

Notes
1. If you include a column-list, it must specify as many columns as there are variables in variable-list. 2. You must use a table-name prex in the designation of the column names. 3. In a MODE ANSI database, the name of a table is qualied by the owner of the table (owner. table-name). You must specify owner when you refer to a table owned by another user. The use of the prex owner is optional in a non-MODE ANSI database. INFORMIX-4GL does check the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 for more information. 4. You can use the upscol utility to create and update the values in syscolval. (See the discussion of the The upscol Utility in Appendix E.) 5. In a non-MODE ANSI database, there is a single syscolval table for all users. The INITIALIZE statement assigns to individual variables in variable-list the DEFAULT values specied in this table. 6. In a MODE ANSI database, each user has his or her own syscolval table. This means that the values entered into these tables apply only to variables that correspond to columns in tables owned by the specied user. If
7-120 INFORMIX-4GL Statement Syntax

INITIALIZE

no owner name is specied, and the user compiling the program owns the table, INFORMIX-4GL uses the values in the syscolval table owned by that user. 7. If any columns corresponding to components of variable-list have not been assigned DEFAULT values in syscolval, INFORMIX-4GL substitutes NULL values. 8. Since upscol does not support DATETIME or INTERVAL values, these data types will default to NULL when you include them in a column-list. 9. You can use the * notation in variable-list and column-list. 10. The TO NULL option requests initialization with the appropriate NULL value for each variable.

Examples
INITIALIZE var1, var2, var3 LIKE tab1.col1, tab1.col2, tab1.col3 INITIALIZE v_cust.* LIKE customer.* INITIALIZE v_orders.* TO NULL INITIALIZE var1, var2, var3 LIKE tab1.var1, eileen.tab2.var2, fred.tab3.var3

Related Statements
LET, VALIDATE

INFORMIX-4GL Statement Syntax

7-121

INPUT

INPUT
Overview
Use the INPUT statement to assign values to program variables from data that the user enters into elds of a screen form.

Syntax
INPUT { BY NAME variable-list [ WITHOUT DEFAULTS ] | variable-list [ WITHOUT DEFAULTS ] FROM { eld-list | screen-record [ [ n ] ] .* } [ , . . . ] } [ ATTRIBUTE ( attribute-list ) ] [ HELP help-number ] [ { BEFORE FIELD eld-sublist | AFTER { FIELD eld-sublist | INPUT } | ON KEY ( key-list ) } statement ... [ NEXT FIELD eld-name ] ... [ EXIT INPUT ] ... ... END INPUT ]

Explanation
INPUT BY NAME

is a required keyword. The INPUT statement allows the user to change the data displayed on the screen. are keywords instructing INFORMIX-4GL to match names of variables to screen eld names. is a list of program variables to display. are keywords to display on the screen the current values in variable-list. is a keyword to specify the screen elds whose values will be assigned to variable-list. is a list of one or more names of screen elds. is the identier of a collection of eld names dened in a form specication as a SCREEN RECORD. is an integer, enclosed in brackets, to specify the row of a screen array (beginning with line 1).

variable-list WITHOUT DEFAULTS

FROM

eld-list screen-record [n]

7-122

INFORMIX-4GL Statement Syntax

INPUT

ATTRIBUTE

is a keyword to specify screen input attributes. is a list (in parentheses) of screen attributes. is a keyword to specify a help message. is an integer to identify a help message for this INPUT statement in the help le that was specied in the OPTIONS statement. cursor enters a eld in the eld-sublist.

(attribute-list)
HELP

help-number

BEFORE FIELD are keywords to transfer control to a 4GL statement when the

eld-sublist
AFTER FIELD AFTER INPUT ON KEY

is a list of one or more of the elds either explicitly or implicitly referenced in the INPUT statement. are keywords to transfer control to a 4GL statement when the cursor leaves a eld in the eld-sublist. are keywords to transfer control to a 4GL statement when the user has nished entering input. are keywords to specify keys of the keyboard. is a list (in parentheses) of key designation(s), usually of function or CTRL keys. If one of these is pressed during input, a 4GL statement is executed. is a 4GL statement. It is executed during input, if BEFORE FIELD, AFTER FIELD, or ON KEY clause conditions are satised. It is executed after input, if an AFTER INPUT clause is used. are keywords that cause INFORMIX-4GL to move the cursor immediately to a specied eld. identies a eld from eld-list or screen-record (or implied by the BY NAME clause). are keywords that direct INFORMIX-4GL to leave the INPUT statement immediately. are keywords that terminate the INPUT statement. These keywords are required if you include a BEFORE clause, AFTER clause, or ON KEY clause.

(key-list)

statement

NEXT FIELD

eld-name
EXIT INPUT END INPUT

INFORMIX-4GL Statement Syntax

7-123

INPUT

Notes
1. When you execute the INPUT statement with the WITHOUT DEFAULTS clause, INFORMIX-4GL displays the current values of variable-list in the screen elds. This option is appropriate when you are requesting input prior to updating an existing row of a table. 2. If an INPUT statement omits the WITHOUT DEFAULTS clause, INFORMIX-4GL displays on the form the default values from the form specication (or from syscolval, if no default valuess were specied by the DEFAULT attribute in the form specication) and initializes the variables in variable-list accordingly. INFORMIX-4GL assigns NULL values to all variables for which no default has been set. This option is appropriate when you are requesting input prior to inserting a new row in a table. 3. The INPUT BY NAME option selects the screen elds based on the identity of the program variable name and the screen eld name. INFORMIX-4GL uses only the sufx portion of the name of the program variable and the screen eld. You must use the FROM option if the sufxes are not unique and unambiguous. 4. If you use the FROM option, the number of variables in variable-list must be the same as the number of eld names in eld-list or screen-record, and of the corresponding data type. 5. INPUT is terminated when the user presses ESCAPE (or the key specied as the Accept key in the OPTIONS statement). For single-item INPUTs (or after the last item of multiple-item INPUTs), a RETURN is equivalent to pressing the Accept key. You can use the AFTER FIELD clause on the last eld to override the terminating power of the RETURN by setting NEXT FIELD to the rst eld. This option wraps the eld-list into a loop. Alternatively, use the INPUT WRAP option in the OPTIONS statement for the same effect. 6. The user triggers the AFTER INPUT clause (and the set of statements that follow that clause) by attempting to terminate the INPUT statement. (See the previous note.) If there is an AFTER INPUT clause, program control passes to the statements following that clause, rather than to the statements following the END INPUT clause. This feature allows the programmer to perform data validity checks before allowing the INPUT statement to terminate. 7. INFORMIX-4GL passes control to the statements following a BEFORE clause when the cursor enters a eld in eld-list. It passes control to the statements following an AFTER clause when the cursor leaves a eld in eld-list (after the user has pressed RETURN, indicating that data has been

7-124

INFORMIX-4GL Statement Syntax

INPUT

entered into the eld). It passes control to the statements following an ON KEY clause after the user presses a key in key-list. 8. If there is no NEXT FIELD statement in the sequence of statements following a BEFORE or AFTER clause, the cursor moves to the next eld in the direction that the user indicated (forward for [ ], [ ], TAB, or RETURN, and backward for [ ] or [ ]). 9. If the user triggers an ON KEY clause while entering data into a eld, INFORMIX-4GL suspends the input of the current eld while it executes the statements in the ON KEY clause. It preserves the input buffer containing the characters that the user typed before triggering the ON KEY clause and restores them when the ON KEY clause returns. It resumes the input in the same eld with the cursor at the end of the buffered list of characters. If you want to use the ON KEY clause to ll the eld with another value, be sure to move to a new eld with the NEXT FIELD statement to prevent the INPUT statement from ignoring the new value. 10. The notation for function keys is F1 through F36. The notation for CONTROL keys is CTRL-key, where key is any letter except A, D, H, L, R, or X. The notation for ESCAPE is ESCAPE or ESC. The notation for the Interrupt key is INTERRUPT. Appendix I, Modifying termcap and terminfo, describes how to verify that the termcap and terminfo entries for your terminal allow INFORMIX-4GL to recognize function keys. 11. By default, both ESCAPE and Interrupt are exits from the INPUT statement. If the DEFER INTERRUPT statement has been executed, an Interrupt causes INFORMIX-4GL to set the global variable int_ag to nonzero and terminate the INPUT statement (unless the function of Interrupt is redened in an ON KEY clause). Otherwise, Interrupt immediately stops the program. 12. These two keys can be in a key-list under the stated conditions:

ESCAPE, if you have specied another key as the Accept key in the OPTIONS statement.

Interrupt, if you have executed a DEFER INTERRUPT statement. (When

the user presses the Interrupt key under these conditions, INFORMIX-4GL executes the statements in the ON KEY clause and sets int_ag to nonzero, but does not terminate the INPUT statement.) Do not use the following keys in a key-list:

CTRL-A, CTRL-D, CTRL-H, CTRL-L, CTRL-R, or CTRL-X, since these keys are reserved for editing functions in the INPUT statement. CTRL-S for XOFF.

Other keys that may have special meaning on your system, such as
13. Use of CTRL-I and CTRL-J in a key-list can conict with normal data entry.
INFORMIX-4GL Statement Syntax 7-125

INPUT

14. In addition to the RETURN, ESCAPE, Interrupt, and Arrow keys, the user can employ the following keys for editing during an INPUT statement:
CTRL-A CTRL-D CTRL-H CTRL-L CTRL-R CTRL-X

toggles between insert and typeover mode. deletes characters from the current cursor position to the end of the eld. moves the cursor nondestructively one space to the left inside a eld. It is equivalent to pressing the [ ] key. moves the cursor nondestructively one space to the right inside a eld. It is equivalent to pressing the [] key. redisplays the screen. deletes the character beneath the cursor.

15. Function ineld(eld) from the function library returns TRUE if the current eld is eld, and FALSE otherwise. Use it to make eld-dependent responses when the user presses a key specied in the key-list of an ON KEY clause. If you call ineld(eld) outside the INPUT statement, it returns a value corresponding to the eld that was current when INPUT was terminated. 16. Do not execute PROMPT, INPUT, or INPUT ARRAY statements within the BEFORE, AFTER, or ON KEY clauses of an INPUT statement. You can, however, call a function that executes one of these statements. 17. If you do not use the ATTRIBUTE clause, the display attributes of the input elds are governed by the INPUT ATTRIBUTE clause of the most recent OPTIONS statement. (The description of the OPTIONS statement lists the order of precedence among different sources of 4GL screen attribute specications.) 18. In an INPUT statement, any screen attributes specied in attribute-list apply to all the elds in eld-list or screen-record. 19. If you use the ATTRIBUTE clause, no default attributes in syscolatt or in the form specication le for elds in eld-list or screen-record apply (including any default values from the DEFAULT attribute). The attribute-list temporarily overrides any attributes specied in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these elds.

7-126

INFORMIX-4GL Statement Syntax

INPUT

20. These keywords can appear in the ATTRIBUTE clause:

WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

You can specify zero or one of the keywords in the left-hand columns, and from zero to three from the right-hand column (but some terminals may not support some combinations). On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. Do not include the equal ( = ) sign, which in this table shows the effect on monochrome terminals of keywords that specify color. These keywords cannot produce the effects suggested by their names unless the termcap or terminfo les and the physical terminals support the attribute. (See Appendix I, Modifying termcap and terminfo.) Note: Some terminal entries in termcap or terminfo include the sg#1 or xmc#1 capabilities. On these terminals, the rst character of variable-list is replaced by a blank if you use the INPUT statement with any display attribute. To be safe, make sure that elds in any line of a screen form begin after column 1, if you specify display attributes. 21. On UNIX systems that use terminfo les rather than termcap, INFORMIX-4GL does not support attributes that specify colors, and the only valid attribute-list keywords are REVERSE and UNDERLINE.

INFORMIX-4GL Statement Syntax

7-127

INPUT

Example
INPUT p_addr.* FROM sc_addr.* ATTRIBUTE (REVERSE RED) HELP 101 BEFORE FIELD fname MESSAGE "Enter first name of customer" BEFORE FIELD lname MESSAGE "Enter last name of customer" AFTER INPUT IF check_zip(p_addr.zipcode, p_addr.city) = FALSE THEN ERROR "Bad zip code for ", p_addr.city NEXT FIELD zipcode END IF ON KEY (F1) IF infield(city) THEN LET p_addr.city = "San Francisco" DISPLAY p_addr.city TO city LET p_addr.state = "CA" DISPLAY p_addr.state TO state NEXT FIELD zipcode END IF END INPUT

Related Statements
DISPLAY, DISPLAY FORM, EXIT, INPUT ARRAY, OPTIONS

7-128

INFORMIX-4GL Statement Syntax

INPUT ARRAY

INPUT ARRAY
Overview
Use the INPUT ARRAY statement to permit the user to enter data onto a screen array and to store the data in a program record array.

Syntax
INPUT ARRAY record-array [ WITHOUT DEFAULTS ] FROM screen-array.* [ HELP help-number ] [ ATTRIBUTE ( attribute-list ) ] [ { BEFORE { ROW | INSERT | DELETE | FIELD eld-sublist } [ , . . . ] | AFTER { ROW | INSERT | DELETE | FIELD eld-sublist | INPUT } [ , . . . ] | ON KEY ( key-list ) } statement ... [ NEXT FIELD eld-name ] ... [ EXIT INPUT ] ... ... END INPUT ]

Explanation
INPUT ARRAY

are required keywords. is a program array name. Usually, record-array is an array of records. are optional keywords to display the current values of record-array. is a required keyword. is the name of a screen record that corresponds to the elds in a row of a screen array. is an optional keyword. is an integer that identies the help message for this INPUT
ARRAY statement in the help le set in the OPTIONS

record-array WITHOUT DEFAULTS

FROM

screen-array
HELP

help-number

statement.
ATTRIBUTE

is a keyword to specify screen input attributes. is a list (in parentheses) of screen attributes.
INFORMIX-4GL Statement Syntax 7-129

(attribute-list)

INPUT ARRAY

BEFORE ROW INSERT DELETE FIELD

is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is an optional keyword. is a list of one or more elds taken from screen-array.*. is an optional keyword. is an optional keyword. are optional keywords. is usually a list of one or more function or CTRL key designations. The list can also include ESCAPE (if you have specied another key as the Accept key in the OPTIONS statement) or Interrupt (if you have executed a DEFER INTERRUPT statement). is any INFORMIX-4GL statement. is an optional statement that causes the cursor to move immediately to the next eld. is a eld name to which the cursor should move. is an optional statement directing INFORMIX-4GL to leave the INPUT ARRAY statement immediately. is a statement that terminates an INPUT ARRAY statement. It is required only when a BEFORE, an AFTER, or an ON KEY clause is used.

eld-sublist
AFTER INPUT ON KEY

key-list

statement
NEXT FIELD

eld-name
EXIT INPUT END INPUT

Notes
1. When you execute the INPUT ARRAY statement with the WITHOUT DEFAULTS clause, INFORMIX-4GL displays in screen-array the values in record-array. You must call set_count() with the number of rows in program-array before the INPUT ARRAY statement. (See a later note for the denition of set_count().) This is appropriate when you are requesting input prior to updating an existing row of a table. 2. When you execute the INPUT ARRAY statement omitting the WITHOUT DEFAULTS clause, INFORMIX-4GL initializes the rst row of screen-array and record-array with the default values from the form specication (or from syscolval if no defaults were set in the form). INFORMIX-4GL assigns NULL values for all variables for which no default has been set. As the cursor moves into a blank line of screen-array, INFORMIX-4GL ini7-130 INFORMIX-4GL Statement Syntax

INPUT ARRAY

tializes that line and the corresponding row of record-array. This is appropriate when you are requesting input prior to inserting new rows in a table. 3. The user can insert rows into the middle of existing rows of record-array by pressing the Insert key (the default is the [ F1 ] function key. You can alter the default with the OPTIONS statement). The user can insert rows at the bottom of existing rows in record-array without pressing the Insert key. 4. If the user attempts to insert rows beyond the dened size of the recordarray, INFORMIX-4GL displays a message that the array is full. 5. The user can delete the current row and move the following rows up to ll the gap by pressing the [ F2 ] function key. You can alter this default with the OPTIONS statement. 6. The user can move the cursor and scroll the displayed rows using the Arrow keys and the function keys [ F3 ] and [ F4 ].
RIGHT ARROW

moves the cursor non-destructively (does not blank out the current contents) one space to the right inside a screen eld. At the end of the screen eld, it causes a jump to the rst character position of the next screen eld. moves the cursor non-destructively one space to the left inside a screen eld. At the end of the screen eld, it causes a jump to the rst character position of the previous screen eld. moves the cursor down one row on the screen. If the cursor was on the last row of the screen array before the user pressed [ ], the displayed data moves up one row. moves the cursor up one row on the screen. If the cursor was on the rst row before the user pressed [ ], the displayed data moves down one row. If the rst program array row is already on the rst screen array row, [ ] does nothing. scrolls the display to the next full page of program array rows. You can reset this key using the OPTIONS statement. scrolls the display to the previous full page of program array rows. You can reset this key using the OPTIONS statement.

LEFT ARROW

DOWN ARROW

UP ARROW

F3

F4

INFORMIX-4GL Statement Syntax

7-131

INPUT ARRAY

7. The INPUT ARRAY statement is terminated when the user enters ESC or the key you specied as the Accept key in the OPTIONS statement. If there is an AFTER INPUT clause, the program control passes to the statements following that clause, rather than to the statements following the END INPUT clause. This feature allows the programmer to perform data validity checks before allowing the INPUT ARRAY statement to terminate. Unlike the INPUT statement, the RETURN does not terminate the statement. 8. The number of variables in a row of record-array must be the same as the number of elds in a row of screen-array and of the corresponding data type. 9. INFORMIX-4GL executes BEFORE, AFTER, and ON KEY clauses in the following order:
BEFORE ROW BEFORE INSERT, DELETE BEFORE FIELD ON KEY AFTER FIELD AFTER INSERT, DELETE AFTER ROW AFTER INPUT

10. INFORMIX-4GL passes control to the statements following a BEFORE ROW clause when

The cursor moves into a new form row. An Insert fails due to lack of space. Insert is aborted with an Interrupt. The user performs a Delete ([ F2 ]).

11. INFORMIX-4GL passes control to the statements following a BEFORE INSERT clause when

The user presses the Insert key ([ F1 ]). A row is added automatically at the end of an array.
12. INFORMIX-4GL passes control to the statements following a BEFORE DELETE clause when the user presses the Delete key ([ F2 ]). 13. INFORMIX-4GL passes control to the statements following a BEFORE FIELD clause when the cursor enters a eld. 14. INFORMIX-4GL passes control to the statements following an ON KEY clause when the user presses a key named in key-list. 15. INFORMIX-4GL passes control to the statements following an AFTER FIELD clause when the cursor leaves a eld.
7-132 INFORMIX-4GL Statement Syntax

INPUT ARRAY

16. INFORMIX-4GL passes control to the statements following an AFTER INSERT clause when the user inserts a row and leaves it (without necessarily entering data into it). 17. INFORMIX-4GL passes control to the statements following an AFTER DELETE clause when the user presses the Delete key ([ F2 ]) and the row has been deleted. 18. INFORMIX-4GL passes control to the statements following an AFTER ROW clause when

The cursor leaves the row by any means. An INSERT is complete.

19. INFORMIX-4GL passes control to the statements following an AFTER INPUT clause when the user presses ESC or the key specied as the Accept key in the OPTIONS statement. 20. If there is no NEXT FIELD statement in the sequence of statements following a BEFORE or AFTER clause, the cursor moves to the next eld in the direction that the user indicated (forward for [ ] or RETURN and backward for [ ]). 21. If the user triggers an ON KEY clause while entering data into a eld, INFORMIX-4GL suspends the input of the current eld while it executes the statements in the ON KEY clause. It preserves the input buffer that contains the characters the user typed before triggering the ON KEY clause, restores them when the ON KEY clause returns, and resumes the input in the same eld with the cursor at the end of the buffered list of characters. If you want to use the ON KEY clause to ll the eld with another value, be sure to move to a new eld with the NEXT FIELD statement to prevent the INPUT ARRAY statement from ignoring the new value. 22. The notation for function keys is F1 through F36. The notation for CTRL keys is CONTROL-key, where key is any letter except A, D, H, L, R, or X. The notation for ESCAPE is ESCAPE or ESC. The notation for the Interrupt key is INTERRUPT. Appendix I, Modifying termcap and terminfo, describes how to verify that the termcap and terminfo entries for your terminal allow INFORMIX-4GL to recognize function keys. 23. By default, both ESCAPE and Interrupt are exits from the INPUT ARRAY statement. If the DEFER INTERRUPT statement has been executed, an Interrupt causes INFORMIX-4GL to set int_ag to nonzero and terminate the INPUT ARRAY statement (unless the function of Interrupt has been redened in an ON KEY clause). Otherwise, an Interrupt causes an immediate program stop.
INFORMIX-4GL Statement Syntax 7-133

INPUT ARRAY

24. You can include the following keys in a key-list under the stated conditions:

ESCAPE, if you have specied another key as the Accept key in the OPTIONS statement. OPTIONS statement.

[ F1 ] if you have specied another key as the Insert key in the [ F2 ] if you have specied another key as the Delete key in the
OPTIONS statement.

[ F3 ] if you have specied another key as the Next key in the OPTIONS
statement.

[ F4 ] if you have specied another key as the Previous key in the

OPTIONS statement.

Interrupt if you have executed a DEFER INTERRUPT statement.

(When the user presses the Interrupt key under these conditions,
INFORMIX-4GL executes the statements in the ON KEY clause and sets int_ag to nonzero, but does not terminate the INPUT ARRAY

statement.) You cannot use the following keys in a key-list:

CTRL-A, CTRL-D, CTRL-H, CTRL-L, CTRL-R, or CTRL-X since these keys are reserved for editing functions in the INPUT ARRAY statement.

Other keys that may have special meaning on your operating system.
25. Use of CTRL-I and CTRL-J in a key-list can conict with normal data entry. 26. In addition to the RETURN, ESCAPE, Interrupt, function, and Arrow keys, the user can employ the following keys for editing during an INPUT ARRAY statement:
CTRL-A CTRL-D CTRL-H CTRL-L CTRL-R CTRL-X

toggles between insert and typeover mode. deletes characters from the current cursor position to the end of the eld. moves the cursor non-destructively one space to the left inside a eld. moves the cursor non-destructively one space to the right inside a eld. redisplays the screen. deletes the character beneath the cursor.

27. The function ineld(eld) from the function library returns TRUE if the current eld is eld and FALSE otherwise. It can be used to make elddependent responses when the user presses a key in the key-list of an
7-134 INFORMIX-4GL Statement Syntax

INPUT ARRAY

ON KEY clause. If you call ineld(eld) outside the INPUT ARRAY statement, it returns a value corresponding to the eld that was current when INPUT ARRAY was terminated.

28. Do not execute PROMPT, INPUT, or INPUT ARRAY statements within the BEFORE, AFTER, or ON KEY clauses of an INPUT ARRAY statement. However, you can call a function that executes one of these statements. 29. Four functions are required to keep track of the relative state of the cursor, the program array, and the screen array. The functions are dened as follows: arr_curr( ) returns the current record-array row. This is the row where the cursor is at the beginning of the [ BEFORE | AFTER ] ROW block, not the row the cursor moves to after execution of the block. returns the total number of lled rows in record-array. returns the current row of screen-array. The current row is dened in the same way that the current row for arr_curr( ) is dened. takes an argument that is the total number of lled rows in record-array. You must call this function before executing the INPUT ARRAY WITHOUT DEFAULTS, so that the program knows the initial value of arr_count( ).

arr_count( ) scr_line( )

set_count( )

30. If you do not use the ATTRIBUTE clause, the display attributes of the input elds are governed by the INPUT ATTRIBUTE clause of the most recent OPTIONS statement. (The description of the OPTIONS statement lists the order of precedence among different sources of 4GL screen attribute specications.) 31. In an INPUT ARRAY statement, any screen attributes specied in attribute-list apply to all the elds in eld-list or screen-record. 32. If you use the ATTRIBUTE clause, none of the default attributes listed in syscolatt or in the form specication le for elds in eld-list or screen-record apply (including any default values from the DEFAULT attribute). The attribute-list temporarily overrides any attributes specied in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these elds.

INFORMIX-4GL Statement Syntax

7-135

INPUT ARRAY

33. These keywords can appear in the ATTRIBUTE clause:

WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

You can specify zero or one of the keywords in the left-hand columns, and from zero to three from the right-hand column (but some terminals may not support some combinations). On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. Do not include the equal ( = ) sign, which in this table shows the effect on monochrome terminals of keywords that specify color. These keywords cannot produce the effects suggested by their names unless the termcap or terminfo les and the physical terminals support the attribute. (See Appendix I, Modifying termcap and terminfo.) Note: Some terminal entries in termcap or terminfo include the sg#1 or xmc#1 capabilities. On these terminals, the rst character of variable-list is replaced by a blank if you use the INPUT statement with any display attribute. To be safe, make sure that elds in any line of the screen form begin after column 1, if you specify display attributes. 34. On UNIX systems that use terminfo les rather than termcap, INFORMIX-4GL does not support attributes that specify colors, and the only valid attribute-list keywords are REVERSE and UNDERLINE.

7-136

INFORMIX-4GL Statement Syntax

INPUT ARRAY

Example
The following program fragment assumes that one column of the screen array (sc_array) contains the row number (row_num) of the program array (pa_array) being displayed there. The next column of sc_array is called rst_data. The program recalculates and displays the row number after the user inserts new rows or deletes old ones.
DEFINE pa_total INTEGER DEFINE pa_curr DEFINE sc_curr INTEGER INTEGER # # # # # # # # total number of rows in program array current program array row number current screen array row number total number of rows in screen array

DEFINE sc_total INTEGER

DEFINE k SMALLINT INPUT ARRAY pa_array FROM sc_array.* AFTER INSERT, DELETE LET pa_curr = arr_curr() LET pa_total = arr_count() LET sc_curr = scr_line() FOR k = pa_curr TO pa_total LET pa_array[k].row_num = k IF sc_curr <= sc_total THEN DISPLAY k TO sc_array[sc_curr].row_num LET sc_curr = sc_curr + 1 END IF END FOR END INPUT

Related Statements
DISPLAY ARRAY, EXIT, INPUT, OPTIONS

INFORMIX-4GL Statement Syntax

7-137

INSERT

INSERT
Overview
Use the INSERT statement to insert one or more new rows into an existing table.

Syntax
INSERT INTO table-name [ ( column-list ) ] { VALUES ( value-list ) | SELECT-statement }

Explanation
INSERT INTO

are required keywords. is the name of the table to which to add rows. is a list of the names of the columns into which to insert data. You can enter one column name or a series of column names, separated by commas. is a keyword. are the values to insert into the columns that you specied. You can enter one or more program variables or constants, separated by commas. is a valid SELECT statement.

table-name column-list

VALUES

value-list

SELECT-statement

Notes
1. INFORMIX-4GL inserts data into the columns in the specied table in the order in which you enter column names. It inserts the rst value that you enter into the rst listed column, the second value into the second listed column, and so on. 2. Entering column names is optional. If you omit them, 4GL assumes that the values are listed in the order in which the columns are listed in the syscolumns systems catalog. Unless you have subsequently used the ALTER TABLE statement to change the order, the order is the same as when the table was created. 3. If you have previously dened a RECORD type program variable LIKE table-name, you can use the program variable in place of a list of values in an INSERT statement.
7-138 INFORMIX-4GL Statement Syntax

INSERT

4. When you execute an INSERT statement, INFORMIX-4GL inserts a single row into the database (unless a SELECT statement appears after the VALUES clause). If you DECLARE a cursor for an INSERT statement and use the OPEN, PUT, FLUSH, and CLOSE statements, INFORMIX-4GL buffers the rows in memory and writes to disk only when the buffer is full. 5. 4GL inserts the rows of data that result from the SELECT statement into the table, just as though you had entered them with the VALUES keyword. 6. You cannot use table-name in the FROM clause of the SELECT statement. The data must be selected from other tables. 7. Do not include an INTO TEMP clause or an ORDER BY clause in the SELECT statement. 8. Although the values that you insert do not have to be of the same data type as the columns themselves, they must be compatible. You can insert only CHAR data into CHAR columns, and only numbers or character representation of number data into number columns. 9. Enter a zero (0) for a SERIAL column in the INSERT statement if you want 4GL to insert the next SERIAL value for the table. Enter a nonzero value for a SERIAL column that does not duplicate a value already in the table, if you want 4GL to use that value. An error occurs if you enter a nonzero value for a SERIAL column that duplicates a value already in the table, and if a UNIQUE index or constraint is dened on the column. In this case, the status is set to a negative value. 10. You can use program variables in the list of values. 11. Enclose string constants (including those that evaluate to DATE, DATETIME, or INTERVAL values) in quotation marks. (See Appendix J for examples of inserting DATETIME and INTERVAL values.) 12. When you create a database with transactions that is not MODE ANSI, each INSERT statement that you execute is treated as a single transaction, even if you do not use the BEGIN WORK and COMMIT WORK or ROLLBACK WORK statements. 13. Each row affected by the INSERT statement within a transaction is locked for the duration of the transaction; therefore, a single INSERT statement that affects a large number of rows locks those rows until the entire operation is completed. If the number of rows affected is very large, you might exceed the limits that your operating system places on the maximum number of simultaneous locks. If this occurs, you may want either to

INFORMIX-4GL Statement Syntax

7-139

INSERT

reduce the scope of the INSERT statement or lock the entire table before executing the statement. See the section Locking in Chapter 3 for a more detailed description of table-level and row-level locking in INFORMIX-4GL. Caution: 4GL makes every possible effort to perform data conversion, including converting the character string 123 into the integer 123. If the data cannot be converted, however, INSERT stops. Unless you have created the database with transactions, all changes made to that point remain, but subsequent rows from the SELECT statement will not be inserted. Data conversion also fails if the target data type cannot hold the value offered. For example, you cannot insert the integer 123456 into a SMALLINT.

Examples
DEFINE ps_customer RECORD LIKE customer.* ... INSERT INTO customer VALUES (ps_customer.*) INSERT INTO customer VALUES (0, f_name, l_name, comp, addr1, addr2, "Palo Alto", "CA", zip, phone)

Related Statements
DECLARE, DELETE, SELECT

7-140

INFORMIX-4GL Statement Syntax

LABEL

LABEL
Overview
Use the LABEL statement to indicate the position in a 4GL program to which the GOTO statement transfers control.

Syntax
LABEL label-id:

Explanation
LABEL

is a required keyword. is an INFORMIX-4GL identier, followed by a colon ( : ).

label-id:

Note
The LABEL statement must be in the same program block (MAIN, FUNCTION, or REPORT) as the GOTO statement with the same label-id. You cannot use GOTO to transfer out of a routine.

Example
IF customer_num < 0 THEN GOTO abort END IF statement ... LABEL abort: statement

Related Statements
GOTO, WHENEVER

INFORMIX-4GL Statement Syntax

7-141

LET

LET
Overview
Use the LET statement to assign a value to a program variable.

Syntax
LET variable = expr

Explanation
LET

variable expr

is a required keyword. is the identier of a simple program variable. is an expression.

Notes
1. The variable can be an element of an ARRAY if that element is a simple variable. 2. As an exception to the .* notation, you may make assignment to a record variable from another record variable using the statement
LET x.* = y.*

This statement is shorthand for a sequence of LET statements assigning values of elements of y to elements of x.

Examples
LET a = b + c LET d[index] = "This is a string" LET newstr = mystr[2,6]

Related Statement
INITIALIZE

7-142

INFORMIX-4GL Statement Syntax

LOAD

LOAD
Overview
Use the LOAD statement to ll an existing table with data taken from an ASCII le.

Syntax
LOAD FROM "pathname" [ DELIMITER "char" ] { INSERT INTO table-name [ ( column-name [ , . . . ] ) ] | INSERT-stmt }

Explanation
LOAD FROM

are required keywords. is a character variable or constant that evaluates to the pathname of a le that contains rows of data. is an optional keyword to indicate that the following char appears at the end of each data eld in the le. is a CHAR variable or a quoted string containing exactly one character. are keywords to specify where to store the data. is the identier of an existing table. is a column name (in parentheses) in table-name. is a character string or variable containing the text of an
INSERT statement in the form shown here, with no VALUES clause or SELECT clause.

pathname
DELIMITER

char
INSERT INTO

table-name column-name
INSERT-stmt

Notes
1. You must have INSERT permission to use the LOAD statement. 2. You can specify an optional list of one or more column names, enclosed within parentheses and separated by commas. 3. Fields in the input le must be separated by a delimiter character. If you do not specify a delimiter in the DELIMITER clause, INFORMIX-4GL

INFORMIX-4GL Statement Syntax

7-143

LOAD

checks the DBDELIMITER environment variable and uses this setting, if it exists. The default delimiter is the vertical bar ( | = ASCII 124). A character column in the input le can contain the delimiter character. Use a backslash to escape the delimiter character and prevent its interpretation as a eld delimiter. 4. The LOAD statement can accept the format of data from a le written by the UNLOAD statement (described later in this chapter). 5. The number of data elds in the load le must equal the number of columns in the table (or in the optional list of column names). 6. The order and data type of the data elds in the le must match the order and data type of the columns specied in the database table. There must be exactly as many delimited elds in each line of the le as the number of columns that you imply or specify in the INTO clause. The length of each data eld must be less than or equal to the length specied for each column of the database table. The value in each eld must be convertible to the data type of the corresponding column. 7. See also The dbload Utility, described in Appendix E, which gives you more options for the format of the input le. 8. A NULL column should be represented in the input le by no characters between delimiters. 9. A blank CHAR column should be represented in the input le by one or more blank characters between delimiters. 10. It is permissible to have leading blanks in number, DATE, and MONEY elds. 11. DATE elds should have the format mm/dd/yyyy. Here mm is the month (1 or 01 for January, and so on), dd is the day, and yyyy is the year. If the format of the DATE eld is mm/dd/yy, the yy is interpreted as 19yy. Any value in a DATE eld must be a legal date (for example, February 30 is illegal). 12. MONEY elds can have leading currency symbols. 13. DATETIME and INTERVAL values must be in character form, showing only eld digits and delimiters (with no type specication or qualiers). The required pattern is the substring of yyyy-mm-dd hh:mi:ss.fff, which corresponds to the qualier associated with the column. 14. If your database has transactions but is not MODE ANSI, you must issue a BEGIN WORK statement before using LOAD. 15. LOAD appends new rows to the table, rather than overwriting existing data.

7-144

INFORMIX-4GL Statement Syntax

LOAD

16. You cannot PREPARE a LOAD statement. 17. The embedded INSERT statement is restricted to the syntax shown here and cannot include a VALUES clause or a SELECT statement. 18. When you execute a LOAD statement, INFORMIX-4GL sets status to zero to indicate success, or to an error number to indicate failure. If an error occurs, the SQLCODE and SQLERRD[2] error codes are set, as described in Chapter 3. In any case, the value of SQLERRD[3] is set to the number of rows that LOAD inserted.

Example
LOAD FROM "/a/data/ord.loadfile" DELIMITER ";" INSERT INTO orders LOAD FROM "/tmp/prices" DELIMITER "," INSERT INTO walter.worktab(price,discount)

Related Statements
UNLOAD, INSERT

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

INFORMIX-4GL Statement Syntax

7-145

LOCK TABLE

LOCK TABLE
Overview
Use the LOCK TABLE statement to control access to a table by other users.

Syntax
LOCK TABLE table-name IN { SHARE | EXCLUSIVE } MODE

Explanation
LOCK TABLE

are required keywords. is the name of the table you want to lock. is a required keyword. is a keyword to give other users read access to the table, but to prevent them from modifying any of the data that it contains. is a keyword to prevent other users from having any access to the table. is a required keyword.

table-name
IN SHARE

EXCLUSIVE MODE

Notes
1. Only one lock can apply to a table at any given time. That is, if a user locks a table (in either SHARE or EXCLUSIVE mode), no other user can lock that table in either mode until the rst user unlocks it. 2. If your database has transactions and is not MODE ANSI, you must issue a BEGIN WORK statement before you can issue the LOCK TABLE statement. 3. You can use the LOCK TABLE statement immediately after beginning a transaction to override row-level locking during the transaction. Normally, each row of a table affected by a statement within a transaction is locked for the duration of the transaction. During transactions that affect a large number of rows, you can exceed the limit that your operating system places on the maximum number of locks. If you lock the entire table at the beginning of the transaction, however, INFORMIX-4GL does not lock each row in the table. You may want to use
7-146 INFORMIX-4GL Statement Syntax

LOCK TABLE

this strategy when executing a transaction that affects a large number of rows or every row in a table. See the section Locking in Chapter 3 for more information about tablelevel and row-level locking in INFORMIX-4GL. 4. You cannot lock system catalogs. (See Appendix B for a list of system catalogs.)

Example
LOCK TABLE orders IN EXCLUSIVE MODE

Related Statements
BEGIN WORK, COMMIT WORK, UNLOCK TABLE

INFORMIX-4GL Statement Syntax

7-147

MAIN

MAIN
Overview
Use the MAIN keyword to introduce the MAIN program block.

Syntax
MAIN statement ... END MAIN

Explanation
MAIN

is a required keyword. is any INFORMIX-4GL statement except MAIN. are required keywords that terminate the MAIN program block.

statement
END MAIN

Note
Every INFORMIX-4GL program must have a MAIN program block and can have one or more functions and reports.

Related Statements
FUNCTION, REPORT

7-148

INFORMIX-4GL Statement Syntax

MENU

MENU
Overview
Use the MENU statement to create a menu screen, to dene user menu options, to designate help numbers, and to dene what statements should be executed for each option.

Syntax
MENU "menu-name" COMMAND { KEY ( key-list ) | [ KEY ( key-list ) ] "menu-option" [ "helpline" ] [ HELP help-number ] } statement ... [ CONTINUE MENU ] ... [ EXIT MENU ] ... [ NEXT OPTION "menu-option" ] ... ... END MENU

Explanation
MENU

is a required keyword. is a character string giving the title of the menu. is a required keyword. is an optional keyword. is a list of one or more letters, function key identiers, or CTRL key identiers, separated by commas. You do not need to put quotation marks around single, printable characters. is a single-word label for a menu option. The menu-option must be enclosed in quotation marks ( " ). is a one-line character string describing the menu-option. The helpline must be enclosed in quotation marks ( " ). is an optional keyword.

menu-name
COMMAND KEY

key-list

menu-option helpline

HELP

INFORMIX-4GL Statement Syntax

7-149

MENU

help-number

is the number of the help message in the help le designated in the OPTIONS statement that corresponds to menu-option. is an INFORMIX-4GL statement that you want executed when the user selects the preceding option. Several statements can exist for each option. is an optional statement that returns program control to the current MENU statement. is an optional statement that causes program control to move to the rst statement following the END MENU keywords. are optional keywords that precede the menu option that you want highlighted when you return to the menu. are required keywords that terminate the MENU statement.

statement

CONTINUE MENU EXIT MENU

NEXT OPTION

END MENU

Notes
1. You must dene at least two options (COMMAND clauses) for each menu. 2. The menu screen displays in a ring menu each of the single-word menuoptions in the order of the COMMAND clauses. 3. When INFORMIX-4GL displays a menu, it adds a colon (:) and a space after the menu name, as well as a space before and after each menu option. If the width of the menu exceeds the number of characters that the screen or a window can display on a single line, INFORMIX-4GL displays the rst page of options followed by an ellipsis ( . . . ) indicating that additional options exist. For example,
menu-name: menu-option1 optional Help line menu-option2 menu-option3 menu-option4 ...

If the user presses the SPACEBAR or [ ] key to move past the rightmost option (menu-option4 in this case), INFORMIX-4GL displays the next
7-150 INFORMIX-4GL Statement Syntax

MENU

page of menu options. In the following example, the ellipses at each end indicate that more menu options exist in both directions.
menu-name: ... menu-option5 optional Help line menu-option6 menu-option7 menu-option8 ...

If the user moves the highlight to the right past menu-option8 in this example, INFORMIX-4GL displays a page of menu options like the following:
menu-name: ... menu-option9 optional Help line menu-option10 menu-option11

Since no ellipsis appears to the right of the menu, the user has come to the last page of the menu options. The user can display the previous page of menu options again by using the [ ] key to move the highlight past the leftmost option in the example. The user can display the rst page of menu options by using the [ ] key to move the highlight past the rightmost option in the example. The [ ] key moves the highlight to the rst item on the previous page; the [ ] key moves the highlight to the rst item on the subsequent page. 4. The help-number refers to the number of the help message in the help le set by the OPTIONS statement. 5. A run-time error occurs if you specify a help-number for an option, and that number does not occur in the help le, or if the help le does not exist. 6. You will incur a run-time error if the menu cannot t on the screen or in the current window.
INFORMIX-4GL Statement Syntax 7-151

MENU

7. INFORMIX-4GL truncates any helpline that exceeds the width of the screen or current window. 8. The user chooses an option by typing one of the letters in key-list. If the KEY clause is not present, the user chooses an option by typing the rst letter of menu-option. 9. After the user chooses an option, INFORMIX-4GL executes the statements immediately following the COMMAND clause. 10. After INFORMIX-4GL executes all the statements for an option, it redisplays the menu, and the user can choose another option. 11. You can execute a CONTINUE MENU statement anywhere within the statements following the COMMAND clause. Use of this statement causes the menu to reappear so that the user can choose another option. 12. The key-list notation to specify function keys is F1 through F36. The notation for CTRL keys is CONTROL-key, where key is any letter except A, D, H, L, R, or X (Some other keys, such as CTRL-S, CTRL-Q, or CTRL-Z might also not be allowed, depending on your implementation of the UNIX operating system.) The key-list notation for the key is ESC or ESCAPE. The notation for the Interrupt key (often DEL or CTRL-C) is INTERRUPT. 13. Unless you use the KEY clause, the initial letters of each menu-option should be different, regardless of case. The values within the key-list must be unambiguous. Each option must be uniquely dened. 14. INFORMIX-4GL produces a run-time error if a menu option exceeds the length of the screen or window. 15. You can add a hidden option to your menu by including a KEY key-list choice in the list of menu COMMANDs. This is demonstrated in the following example.

7-152

INFORMIX-4GL Statement Syntax

MENU

Example
MENU "TOP LEVEL" COMMAND "Add" "Add a row to the database" HELP 12 ... COMMAND "Find" "Find a row in the database" HELP 13 ... COMMAND "Change" "Update a row in the database" HELP 14 ... COMMAND "Delete" "Delete a row from the database" HELP 15 ... COMMAND key ("!") CALL bang() ... COMMAND "Exit" "Return to operating system" HELP 16 EXIT PROGRAM END MENU

These statements produce the following menu:

TOP LEVEL: Add Find Change Add a row to the database Delete Exit

Related Command
OPTIONS

INFORMIX-4GL Statement Syntax

7-153

MESSAGE

MESSAGE
Overview
Use the MESSAGE statement to display a character string on the Message line.

Syntax
MESSAGE display-list [ ATTRIBUTE ( attribute-list ) ]

Explanation
MESSAGE

is a required keyword. is a list of one or more program variables and/or string constants (enclosed in quotation marks), separated by commas. is an optional keyword. is a list of one or more screen attributes, separated by commas.

display-list
ATTRIBUTE

attribute-list

Notes
1. INFORMIX-4GL generates the message by replacing the variables in display-list with their values and concatenating the resulting strings. 2. The default Message line is the same line used to display the helpline in menus. See the OPTIONS statement for information about resetting this line to a different position. 3. The default attribute for the Message line is the NORMAL display. You can alter the default attribute with the ATTRIBUTE clause.

7-154

INFORMIX-4GL Statement Syntax

MESSAGE

4. The following list shows the screen attributes allowed in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. If you have a colornames le, you can use the color names listed there. (See Appendix I.)

Example
MESSAGE "Enter the order data."

Related Statements
OPTIONS, PROMPT

INFORMIX-4GL Statement Syntax

7-155

OPEN

OPEN
Overview
Use the OPEN statement to establish search criteria for a SELECT cursor and initialize the system for subsequent FETCHes, or to set up an INSERT buffer for an INSERT cursor that references program variables.

Syntax
OPEN cursor-name [ USING variable-list ]

Explanation
OPEN

is a required keyword. is the identier of a previously declared cursor. is a keyword, needed only if the cursor expects user-supplied search values. is a list of program variables, separated by commas, corresponding to the ? parameters in a query associated with a SELECT cursor.

cursor-name
USING

variable-list

Notes
1. If cursor-name is associated with a SELECT statement, the OPEN statement examines the content of the program variables and, using these values for the parameters in the SELECT statement, establishes the search criteria for determining the logical set of rows that satises the WHERE clause. This set of rows is called the active set. It leaves the cursor in an open state and pointing before the rst row of the active set. 2. The active set is a dynamic collection of rows; it is not xed at the time when the OPEN statement is executed. Rows meeting the WHERE criteria and qualied for FETCHing depend on the activity in the table. 3. Once the active set for a SELECT cursor is determined, the program variables are not reexamined until you reopen the cursor. 4. If a SELECT cursor is already open, an OPEN statement closes the cursor and reopens it, creating a new active set, based on the current values of the program variables.

7-156

INFORMIX-4GL Statement Syntax

OPEN

5. The FOREACH statement performs an implied OPEN statement. You cannot use the FOREACH statement if the OPEN statement for a SELECT cursor must have a USING clause to supply values for ? parameters in a PREPAREd SELECT statement. 6. If cursor-name is associated with an INSERT statement (rather than a SELECT statement), the OPEN statement cannot include a USING clause. 7. If you reopen an INSERT cursor that is already open, INFORMIX-4GL ushes the INSERT buffer (that is, INFORMIX-4GL inserts any rows currently in the INSERT buffer into the database table). The global variable SQLCA. SQLERRD [3] is set to the number of rows successfully inserted into the database. 8. A cursor declared FOR UPDATE is called an UPDATE cursor. In a database that uses transactions, you cannot OPEN an UPDATE cursor outside a transaction unless it also was declared WITH HOLD. You can OPEN a nonUPDATE cursor, or one declared WITH HOLD, at any time. In a non-MODE ANSI database that has transactions, a transaction begins with a BEGIN WORK statement and ends with a COMMIT WORK or ROLLBACK WORK statement. In a MODE ANSI database, no BEGIN WORK is required; all actions take place inside transactions. 9. If you declare a cursor with a DECLARE statement that includes the SELECT or INSERT keywords, INFORMIX-4GL implicitly PREPAREs the statement when you OPEN that cursor. 10. The database engine allocates resources to explicitly or implicitly PREPAREd statements. If you release resources with FREE cursor-name, you cannot use that cursor unless you OPEN it again. If you specify FREE statement-id, you cannot OPEN a cursor that references statement-id unless you PREPARE that statement again.

Examples
DECLARE s_curs CURSOR FOR SELECT * FROM orders OPEN s_curs DECLARE q_cursor CURSOR FOR SELECT o.order_num, SUM(total_price) FROM orders o, items i WHERE o.order_date > "06/04/86" AND o.customer_num = 110 AND o.order_num = i.order_num GROUP BY o.order_num OPEN q_cursor

INFORMIX-4GL Statement Syntax

7-157

OPEN

Related Statements
CLOSE, DECLARE, FETCH, FLUSH, FOREACH, FREE, PREPARE, PUT

7-158

INFORMIX-4GL Statement Syntax

OPEN FORM

OPEN FORM
Overview
Use the OPEN FORM statement to associate an INFORMIX-4GL identier with a pre-compiled screen form.

Syntax
OPEN FORM form-name FROM "form-le"

Explanation
OPEN FORM

are required keywords. is an INFORMIX-4GL identier. is a required keyword. is the pathname of a compiled screen form (omitting the extension .frm). form-le must be enclosed in quotation marks.

form-name
FROM

form-le

Notes
1. You must open a form before you can display it. 2. When you execute the OPEN FORM statement, the compiled form is loaded into and kept in memory until you execute a CLOSE FORM statement for that form. If you have displayed another form and wish to regain the space used by the rst form, you can execute CLOSE FORM on the old form. The CLOSE FORM statement is a memory-management feature only; it does not affect the logic of the program.

Example
OPEN FORM order_form FROM "orderform"

Related Statements
CLOSE FORM, DISPLAY FORM

INFORMIX-4GL Statement Syntax

7-159

OPEN WINDOW

OPEN WINDOW
Overview
Use the OPEN WINDOW statement to create and open a window at a specied origin on the screen. This can optionally display a form.

Syntax
OPEN WINDOW window-name AT row, column WITH { integer ROWS, integer COLUMNS | FORM "form-le" } [ ATTRIBUTE ( attribute-list ) ]

Explanation
OPEN WINDOW

are required keywords. is the name of the window that you want to create. is a required keyword. is an integer or integer variable between one and the maximum number of lines allowed by your terminal (usually 24), indicating the line on the screen where the top of the window will appear. is an integer or integer variable between one and the maximum number of columns allowed by your terminal (usually 80), indicating the column of the screen where the left margin of the window will appear. is a required keyword to specify the vertical and horizontal dimensions of the window, in characters. is an integer or integer variable. is a keyword to specify the height of the window. is a keyword to specify the width of the window. is an optional keyword. is the pathname of a compiled form specication le (excluding the .frm extension). is an optional keyword. is a list of one or more window display attributes.

window-name
AT

row

column

WITH

integer
ROWS COLUMNS FORM

form-le
ATTRIBUTE

(attribute-list)

7-160

INFORMIX-4GL Statement Syntax

OPEN WINDOW

Notes
1. When you open a window, INFORMIX-4GL saves any current window and makes the new window the current window. 2. The window-name is a 4GL identier whose scope is global to the entire program. It must begin with a letter. Up to 17 additional characters can include letters, numbers, and underscores ( _ ). 3. You can use the WITH integer ROWS, integer COLUMNS clause to specify explicit dimensions for the window. Alternatively, you can include a WITH FORM clause, so that INFORMIX-4GL automatically opens a window sized to the screen layout of form-le and displays the form. INFORMIX-4GL determines the width of the window from the rightmost character of the screen form and calculates the length of the window as this sum:
( FORM LINE (relative to the first line of the window) -1 ) + form-length + 1 (for the COMMENT LINE )

Unless you specify FORM LINE in an ATTRIBUTE clause or in the OPTIONS statement, the default value of this sum is form-length + 1, where form-length is the number of lines in the screen layout of form-le. (Chapter 4 describes the screen layout.) 4. The WITH FORM clause is convenient when you want to open a window that displays a single form. You cannot use a CLOSE FORM statement to close a form that the WITH FORM clause displays, but CLOSE WINDOW closes the form automatically. If you want to display more than one form in a window or want a window larger than the one that INFORMIX-4GL creates when it executes the WITH FORM clause, you must specify explicit window dimensions with the WITH integer ROWS, integer COLUMNS clause. In that case, you must also open, display, and close the form(s) yourself. 5. When you OPEN a window, INFORMIX-4GL uses line-values specied in the most recently executed OPTIONS statement for the Prompt, Message, Form, and Comment lines. Values are relative to the rst or last line of the newly opened window. To change the values for these reserved lines (without disabling the OPTIONS statement specications for other windows), you can include an ATTRIBUTE clause. 6. An ATTRIBUTE clause in the OPEN WINDOW statement can include the following attributes:

INFORMIX-4GL Statement Syntax

7-161

OPEN WINDOW

Attribute BORDER color (see note 13) REVERSE PROMPT LINE line-value MESSAGE LINE line-value FORM LINE line-value COMMENT LINE line-value

Default Setting No border The default foreground color on your terminal No reverse video FIRST ( = 1 ) FIRST + 1 ( = 2 ) FIRST + 2 ( = 3 ) LAST - 1 (for the screen) LAST (for all other windows)

After the PROMPT, MESSAGE, and COMMENT keywords, line-value can be an integer, a program variable, FIRST plus an optional integer, or LAST minus an optional integer. For the Form line, line-value can be an integer, a program variable, or FIRST plus an optional integer. 7. If a window is not large enough to contain the specied value for one or more of these reserved lines, INFORMIX-4GL increases its line-value to FIRST or decreases it to LAST, as appropriate. 8. If the window is not wide enough to display part of the text that you specify with the PROMPT, MESSAGE, or DISPLAY statement (or with the COMMENTS attribute of a screen form), INFORMIX-4GL generates a runtime error. 9. INFORMIX-4GL displays system error messages and text associated with the ERROR statement in a borderless window on the Error line. INFORMIX-4GL opens the window as necessary and closes it at the next keystroke to erase the message. Since the position of the Error line is relative to the screen, rather than to the current window, the ATTRIBUTE clause of an OPEN WINDOW statement cannot change its location. 10. If a window and its border (if any) exceed the physical limits of the screen, INFORMIX-4GL generates a run-time error.

7-162

INFORMIX-4GL Statement Syntax

OPEN WINDOW

11. When you use the BORDER attribute, INFORMIX-4GL draws a border outside the window area that you specify. For example, if you open the following window
OPEN WINDOW w1 AT 10,10 WITH 5 ROWS, 30 COLUMNS ATTRIBUTE (BORDER) INFORMIX-4GL displays a border with coordinates like those in the fol-

lowing example:
(9,9) (9,40) +------------------------------+ | | | | | | | | | | +------------------------------+ (15,9) (15,40) INFORMIX-4GL draws the border with characters dened in the termcap

or terminfo les. You can specify alternative border characters in these les. Otherwise, INFORMIX-4GL uses the hyphen ( - ) for horizontal lines, the vertical bar ( | ) for vertical lines, and the plus ( + ) sign for corners, as illustrated in the preceding example. See Appendix I, Modifying termcap and terminfo, and the manual that comes with your terminal for information about making changes to your termcap or terminfo les. Note: Some terminals do not support the features described in Appendix I. 12. The termcap or terminfo entries for some terminals include, respectively, the sg#1 or xmc#1 capabilities. On these terminals, INFORMIX-4GL reserves an additional column to the left and to the right of the window. These two columns are reserved, whether you specify a border or not. INFORMIX-4GL uses a total of four extra columns for bordered windows on these terminals: two columns to the left of the window, and two columns to the right. 13. Use any of the following keywords for color in an ATTRIBUTE clause to specify the foreground of a window:
WHITE YELLOW MAGENTA RED CYAN GREEN BLUE BLACK DIM INVISIBLE BOLD NORMAL

14. If you specify a color in the ATTRIBUTE clause of an OPEN WINDOW statement, it becomes the default color for anything displayed in the window except a menu. You can override the default color for a particular display by specifying a different color in the ATTRIBUTE clause of a CONSTRUCT,
INFORMIX-4GL Statement Syntax 7-163

OPEN WINDOW

DISPLAY, DISPLAY ARRAY, DISPLAY FORM, INPUT, or INPUT ARRAY

statement. 15. Windows are stacked in the order that they are opened. See the CURRENT WINDOW and CLOSE WINDOW statements for information about how these statements affect the window stack.

Examples
OPEN WINDOW w1 AT 5, 5 WITH FORM "custform" OPEN WINDOW w2 AT 10, 12 WITH 5 ROWS, 40 COLUMNS ATTRIBUTE (BORDER, PROMPT LINE 3)

Related Statements
CLEAR WINDOW, CLOSE FORM, CLOSE WINDOW, CURRENT WINDOW, OPTIONS

7-164

INFORMIX-4GL Statement Syntax

OPTIONS

OPTIONS
Overview
The OPTIONS statement can modify the reserved line positions and input or display attributes for screen forms, and can change the keys for screen operations and program aids (like help messages).

Syntax
OPTIONS {MESSAGE LINE line-value | PROMPT LINE line-value | COMMENT LINE line-value | ERROR LINE line-value | FORM LINE line-value | INPUT { WRAP | NO WRAP } | INSERT KEY key-name | DELETE KEY key-name | NEXT KEY key-name | PREVIOUS KEY key-name | ACCEPT KEY key-name | HELP FILE "help-le" | HELP KEY key-name | INPUT ATTRIBUTE ( attribute-list ) | DISPLAY ATTRIBUTE ( attribute-list ) } [ , . . . ]

Explanation
OPTIONS

is a required keyword. is an integer expression, indicating the line of the current window or screen to display the reserved line specied by the preceding keywords. The line-value can include the keywords FIRST or LAST. are optional keywords to position the Message line. The default line-value is FIRST + 1 (that is, line 2 of the current window). are optional keywords to position the Prompt line. The default line-value is the FIRST window line. are optional keywords to position the Comment line. The default line-value is LAST - 1 for the screen, and LAST for all other windows. are optional keywords to position the Error line. The default line-value is the LAST line of the screen.
INFORMIX-4GL Statement Syntax 7-165

line-value

MESSAGE LINE PROMPT LINE COMMENT LINE

ERROR LINE

OPTIONS

FORM LINE

are optional keywords to position the rst line of a form. The default line-value is FIRST + 2 (that is, the form will begin on line 3 of the current window). are optional keywords indicating that the cursor wraps around the list of input elds during the execution of an INPUT or CONSTRUCT statement until the Accept key is pressed. The default is INPUT NO WRAP. are optional keywords indicating that the INPUT or CONSTRUCT statement terminates upon a RETURN after the last eld. This option is the default. designates or a function or CTRL key whose action is specied by preceding keywords. are optional keywords to specify the key that opens up a line for data insertion in INPUT ARRAY statements. If you do not specify an Insert key, the default is [ F1 ]. are optional keywords to specify the key that deletes a line in INPUT ARRAY statements. The default is [ F2 ]. are optional keywords to specify the key that scrolls to the next page in the INPUT ARRAY or DISPLAY ARRAY statement. The default is [ F3 ].

INPUT WRAP

INPUT NO WRAP

key-name
INSERT KEY

DELETE KEY NEXT KEY

PREVIOUS KEY are optional keywords to specify the key that scrolls to the previous page in the INPUT ARRAY or DISPLAY ARRAY statement. The default is [ F4 ]. ACCEPT KEY

are optional keywords specifying the key to terminate the INPUT, INPUT ARRAY, DISPLAY ARRAY, and CONSTRUCT statements. If you do not specify an Accept key, the default is the ESCAPE key. are optional keywords to specify the le that contains programmer-dened help messages. (Appendix E describes mkmessage, the help message utility.) is the pathname, enclosed in quotation ( " ) marks, of the le containing help messages. are optional keywords to specify the key that displays help messages. The default is CTRL-W. are optional keywords to specify eld attributes that are in effect when data values are entered. is a list of one or more screen display attributes, or the keywords FORM or WINDOW.

HELP FILE

help-le
HELP KEY

INPUT ATTRIBUTE attribute-list

7-166

INFORMIX-4GL Statement Syntax

OPTIONS

DISPLAY ATTRIBUTE

are optional keywords to specify screen attributes that are in effect when data values are displayed.

Notes
1. You can use the OPTIONS statement to change the defaults listed earlier. (If you list more than one item in an OPTIONS statement, make sure to separate the items with commas.) 2. You can issue the OPTIONS statement more than once. The values set in the last OPTIONS statement encountered at run time prevail. 3. The line-value to position the Form line can be either integer or FIRST [ + integer]. The line-value of the other reserved lines can have any of the following formats:
integer FIRST LAST [ + integer ] [ - integer ]

Here FIRST is the rst line of the current window (line 1), and LAST is the last line of the current window. 4. The line-value for the Error line is relative to the screen, rather than to the current window. The line-value of any other reserved line is relative to the rst line of the current window (or to the screen, if that is the current window). 5. The key-name notation to specify function keys is F1 through F36. The key-name notation for CTRL keys is CTRL-key, where key is any letter except A, D, H, L, Q, R, S, or X. The key-name notation for is ESC or ESCAPE. 6. INFORMIX-4GL uses the CTRL keys CTRL-A, CTRL-D, CTRL-H, CTRL-L, CTRL-R, and CTRL-X for screen-editing functions. You cannot use these for the Insert key, Delete key, Next key, Previous key, Accept key, or Help key. In addition, you might not be able to use some other keys, such as CTRL-C, CTRL-S, CTRL-Q, or CTRL-Z, depending on your implementation of the UNIX operating system. 7. During a CONSTRUCT, DISPLAY, DISPLAY ARRAY, DISPLAY FORM, INPUT, or INPUT ARRAY statement, INFORMIX-4GL checks for attributes and reserved line positions in the following order of precedence (from highest to lowest): 1. Any ATTRIBUTE clause in the current statement. 2. Any attributes from eld descriptions in the current form le. (See the Attributes Syntax section of Chapter 4.)
INFORMIX-4GL Statement Syntax 7-167

OPTIONS

3. Any default attributes in the syscolatt table of elds linked to database columns. (See the description of the The upscol Utility in Appendix E.) 4. Any attributes and reserved line positions specied in the most recent OPTIONS statement. 5. Any ATTRIBUTE clause for the current form in the most recent DISPLAY FORM statement. 6. Any ATTRIBUTE clause of the current window in the most recent OPEN WINDOW statement. 7. The default reserved line positions and the default foreground color on your terminal. 8. The attribute-list supports the same keyword options as in the ATTRIBUTE clause of the DISPLAY statement, plus two additional options, FORM and WINDOW:
WHITE YELLOW MAGENTA RED CYAN GREEN BLUE BLACK DIM INVISIBLE BOLD NORMAL REVERSE BLINK UNDERLINE FORM WINDOW

9. The INPUT ATTRIBUTE clause species the screen attributes to be used during a CONSTRUCT, INPUT, or INPUT ARRAY statement when no attribute-list is specied in those statements or in the specication le of the current form. 10. Similarly, the DISPLAY ATTRIBUTE clause species the screen attributes to be used during a DISPLAY or DISPLAY ARRAY statement when no attribute-list is specied in those statements or in the specication le of the current form. 11. Include the FORM keyword with a DISPLAY ATTRIBUTE or INPUT ATTRIBUTE statement to instruct INFORMIX-4GL to use the display attributes of the current form. Use the WINDOW keyword of the same statements to instruct INFORMIX-4GL to use the display attributes of the current window.

7-168

INFORMIX-4GL Statement Syntax

OPTIONS

Examples
The following statement sets three reserved line positions and species the Next and Previous keys:
OPTIONS MESSAGE LINE 23, PROMPT LINE LAST-2, FORM LINE FIRST, NEXT KEY CONTROL-N, PREVIOUS KEY CONTROL-P

The following statement causes screen elds to appear as green where values are input, regardless of the foreground form color or window color:
OPTIONS INPUT ATTRIBUTE (green)

Related Statements
CONSTRUCT, DISPLAY, DISPLAY ARRAY, DISPLAY FORM, ERROR, INPUT, INPUT ARRAY, MENU, MESSAGE, OPEN FORM, OPEN WINDOW, PROMPT

INFORMIX-4GL Statement Syntax

7-169

OUTPUT TO REPORT

OUTPUT TO REPORT
Overview
Use the OUTPUT TO REPORT statement to pass a single row of data to a report.

Syntax
OUTPUT TO REPORT report-name (expr-list)

Explanation
OUTPUT TO REPORT report-name expr-list are required keywords. is the identier of a report. is a list of one or more expressions, separated by commas.

Notes
1. Ordinarily, you will use the OUTPUT TO REPORT statement within a loop that passes data to a report. 2. The number of expressions in expr-list should agree with the number and type of arguments in the REPORT routine.

Example
OUTPUT TO REPORT rept1 (v_pers.*)

Related Statements
FINISH REPORT, REPORT, START REPORT

7-170

INFORMIX-4GL Statement Syntax

PREPARE

PREPARE
Overview
Use the PREPARE statement to preprocess an SQL statement for later execution. The SQL statements are listed in Chapter 3.

Syntax
PREPARE statement-id FROM string-spec

Explanation:
PREPARE

is a required keyword. is an SQL identier for a statement. is a required keyword. is either a string constant enclosed in quotation marks or a CHAR type program variable. The string-spec must contain an SQL statement.

statement-id
FROM

string-spec

Notes
1. The statement(s) described in string-spec cannot contain program variables. Use a question mark ( ? ) as a placeholder for an input value that will be supplied in an EXECUTE, OPEN, or PUT statement. Do not use a question mark as a placeholder for an SQL identier such as a database name, table name, column name, or user name. 2. If you PREPARE a SELECT statement for use with the DECLARE statement, string-spec can include a SELECT statement followed by a FOR UPDATE clause. 3. The string-spec cannot include any of the following statements: CLOSE, DECLARE, EXECUTE, FETCH, LOAD, OPEN, PREPARE, UNLOAD, and WHENEVER. 4. Do not PREPARE a SELECT statement with an INTO clause. 5. The scope of statement-id is the module in which you PREPARE it. You can refer to it by name in functions contained in the same module. It is not, however, a global identier that you can reference in another source le.

INFORMIX-4GL Statement Syntax

7-171

PREPARE

6. INFORMIX-4GL can execute several SQL statements as one action if you preprocess them all in the same PREPARE statement. To PREPARE multiple SQL statements, the string-spec must use the comma ( , ) concatenation operator between consecutive strings that contain each SQL statement. You must also terminate each string (except the last) with a semicolon ( ; ) symbol before the right-hand quotation ( " ) mark. For an example, see the section Preparing Multiple SQL Statements in Chapter 3. (The statements cannot include SELECT, DATABASE, CLOSE DATABASE, CREATE DATABASE, or DROP DATABASE.) 7. Within a module, statement-id can apply to only one SQL statement or sequence of statements. Do not specify the same statement-name in another PREPARE statement in the same module. 8. You can use a subsequent FREE statement to release the database engine resources that have been allocated to statement-id.

Example
LET select_2 = "select * from orders ", "where customer_num = ? and ", "order_date > ?" PREPARE query_2 FROM select_2

Related Statements
DECLARE, EXECUTE, FOREACH, FREE, OPEN

7-172

INFORMIX-4GL Statement Syntax

PROMPT

PROMPT
Overview
Use the PROMPT statement to prompt the user for keyboard input, and to accept a value entered by the user.

Syntax
PROMPT display-list [ ATTRIBUTE ( attribute-list) ] FOR [ CHAR ] variable [ HELP help-number ] [ ATTRIBUTE ( attribute-list) ] [ ON KEY ( key-list) statement ... ... END PROMPT ]

Explanation
PROMPT

is a required keyword. is a list of one or more program variables or string constants, separated by commas. is a keyword to specify screen display attributes. is a list (in parentheses) of one or more screen display attributes, separated by commas. is a required keyword. is an optional keyword. is the program variable that will contain the value typed in by the user. is an optional keyword. is an integer that identies the help message for this PROMPT statement in the help le designated in the OPTIONS statement. are optional keywords. is a list of one or more function or CTRL key designations. It can also include ESCAPE (if you have specied another key as the Accept key in the OPTIONS statement) or INTERRUPT (if you have executed a DEFER INTERRUPT statement).
INFORMIX-4GL Statement Syntax 7-173

display-list
ATTRIBUTE

(attribute-list)
FOR CHAR

variable
HELP

help-number

ON KEY

key-list

PROMPT

statement END PROMPT

is an INFORMIX-4GL statement. are keywords to terminate a PROMPT statement (required only if an ON KEY clause is used).

Notes
1. INFORMIX-4GL displays the string generated by replacing the variables in display-list with their current values on the Prompt line if an open form is displayed. The prompt occurs at the current cursor position if no form is displayed and

It is preceded by a DISPLAY statement with no AT clause. It is the rst printing statement in the program. The screen is cleared.
2. The PROMPT statement returns the value entered by the user in variable. For a string variable, the value returned can include spaces. 3. The use of the CHAR option causes PROMPT to accept a single character input without requiring a carriage return. 4. If INFORMIX-4GL cannot convert the value entered by the user to the data type of variable, it returns a negative error code in the global variable status and the value of variable is undetermined. 5. You can use these keys in a key-list under the stated conditions:

Function keys. CTRL keys (except as noted later). ESCAPE (if you have specied another key as the Accept key in the
OPTIONS statement).

Interrupt, if you have executed a DEFER INTERRUPT statement. (When

the user presses the Interrupt key under these conditions, INFORMIX-4GL executes the statements in the ON KEY clause and sets int_ag to nonzero.) You cannot use the following keys in a key-list:

CTRL-A, CTRL-D, CTRL-H, CTRL-L, CTRL-R, or CTRL-X since these CTRL keys are reserved for editing functions in the CONSTRUCT, INPUT, and INPUT ARRAY statements.

Other keys like CTRL-S that may have special meaning on your implementation of UNIX. 6. INFORMIX-4GL terminates PROMPT and passes control to the statements following an ON KEY clause when the user presses a key specied in key7-174 INFORMIX-4GL Statement Syntax

PROMPT

list. In this case, the value in variable is undetermined. After completing the ON KEY clause, INFORMIX-4GL passes control to the statements following END PROMPT. 7. The notation for function keys is F1 through F36. The notation for CONTROL keys is CTRL-key, where key is any letter except A, D, H, L, R, or X. The notation for ESCAPE is ESC or ESCAPE. The notation for the Interrupt key (often CTRL-C or DEL) is INTERRUPT. 8. Do not execute PROMPT, INPUT, or INPUT ARRAY statements within the ON KEY clause of a PROMPT statement. However, you can call a function that executes one of these statements. If you include an ON KEY clause, any HELP or ATTRIBUTE specications must appear before the ON KEY clause, not after it. 9. The rst ATTRIBUTE clause applies to the display-list, while the second is in effect during input. 10. The HELP clause and the second ATTRIBUTE clause can appear in any order. 11. Neither ATTRIBUTE clause can be in effect when the terminal is in line mode. The terminal is in line mode until the rst time that a screen-I/O statement is executed. It returns to line mode when you issue any DISPLAY statement that has no BY NAME, TO, or AT clause. 12. The attribute-list temporarily overrides any attributes specied in an OPTIONS or OPEN WINDOW statement. 13. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL YELLOW = BOLD MAGENTA = BOLD RED = BOLD CYAN = DIM GREEN = DIM BLUE = DIM BLACK = INVISIBLE REVERSE BLINK UNDERLINE

You can specify zero or one of the keywords in the left-hand columns, and from zero to three from the right-hand column (but some terminals may not support some combinations). On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM as BLUE, and INVISIBLE as BLACK. Do not include the equal ( = ) sign, which in this table shows the effect on monochrome terminals of keywords that specify color. These keywords cannot produce the effects suggested by their names unless the termcap or terminfo les and the physical terminals support the attribute. (See Appendix I, Modifying termcap and terminfo.)

INFORMIX-4GL Statement Syntax

7-175

PROMPT

Note: Some terminal entries in termcap or terminfo include the sg#1 or xmc#1 capabilities. On these terminals, the rst character of display-list is replaced by a blank if you use the PROMPT statement with any display attribute. To be safe, make sure that the rst character of the display-list is a blank if you specify any display attributes. 14. On UNIX systems that use terminfo les rather than termcap, INFORMIX-4GL does not support attributes that specify colors, and the only valid attribute-list keywords are REVERSE and UNDERLINE.

Example
PROMPT "Enter the Customer Number: " FOR v.cust_no ON KEY (CONTROL-E) GOTO stop_now: END PROMPT

Related Statements
DISPLAY, DISPLAY ARRAY, INPUT, INPUT ARRAY, OPTIONS

7-176

INFORMIX-4GL Statement Syntax

PUT

PUT
Overview
Use the PUT statement to store a row in the INSERT buffer for later insertion into the database table.

Syntax
PUT cursor-name [ FROM variable-list ]

Explanation
PUT

is a required keyword. is the name of a cursor that has been DECLAREd for an INSERT statement. is an optional keyword. is a list of program variables, separated by commas, corresponding to the ? parameters in the PREPAREd INSERT statement associated with cursor-name.

cursor-name
FROM

variable-list

Notes
1. You can execute the PUT statement only if cursor-name has been DECLAREd for an INSERT statement and is in an open state. Such a cursor is referred to as an INSERT cursor. 2. The PUT statement puts a row in the buffer created when cursor-name was OPENed. When you ush the buffer (by executing a series of PUT statements, a CLOSE statement, or a FLUSH statement), INFORMIX-4GL inserts the buffered rows into the database table as a block. 3. INFORMIX-4GL does not create an INSERT buffer for a cursor associated with an INSERT statement that contains only constants in the VALUES clause. If you execute a PUT statement for such a cursor, INFORMIX-4GL increments a counter that keeps track of the number of rows to be inserted into the database. The database is updated only when you issue a FLUSH or CLOSE statement. 4. You close a cursor by issuing a CLOSE statement. Exiting a program without closing an insert cursor leaves the buffer unushed. Rows inserted

INFORMIX-4GL Statement Syntax

7-177

PUT

into the buffer since the last ush are lost. You cannot rely on the end of program to close the cursor and ush the buffer. 5. The global variables status (whose value is received from SQLCA.SQLCODE) and SQLCA.SQLERRD[3] indicate the result of each PUT statement. If INFORMIX-4GL simply puts a row in the INSERT buffer, it sets status and SQLCA.SQLERRD[3] to zero. If, as the result of a PUT statement, INFORMIX-4GL successfully inserts a block of rows into the database, it sets status to zero and sets SQLCA.SQLERRD[3] to the number of rows inserted. If, as the result of a PUT statement, INFORMIX-4GL is unsuccessful in its attempt to insert an entire block of rows into the database, it sets status to a negative number (specically, the number of the error message) and sets SQLCA.SQLERRD[3] to the number of rows successfully inserted into the database. 6. Whenever the buffer is ushed, SQLCA.SQLERRD[3] is set to the number of rows successfully inserted into the database. If an error occurs during the ushing of a buffer, the buffered rows that follow the last successfully inserted row are discarded. 7. If your database has transactions, you must issue the PUT statement within a transaction. 8. If cursor-name has been DECLAREd for a PREPAREd INSERT statement that includes ? parameters, you must use the PUT statement with a FROM clause. After the FROM keyword, you can list the variable(s) containing the value(s) that INFORMIX-4GL substitutes for the ? parameters in the PREPAREd INSERT statement.

Examples
DECLARE icurs CURSOR FOR INSERT INTO manufact VALUES (m_code, m_name) OPEN icurs PUT icurs PREPARE ins_stmt FROM "INSERT INTO manufact VALUES (?, ?)" DECLARE ins_curs CURSOR FOR ins_stmt OPEN ins_curs PUT ins_curs FROM m_code, m_name

Related Statements
CLOSE, DECLARE, FLUSH, OPEN, PREPARE

7-178

INFORMIX-4GL Statement Syntax

RECOVER TABLE

RECOVER TABLE
Overview
In the event of a system failure, use the RECOVER TABLE statement to restore a database table from a backup copy and an audit trail le.

Syntax
RECOVER TABLE table-name

Explanation
RECOVER TABLE

are required keywords. is the name of the table you want to recover.

table-name

Notes
1. Once you have recovered the table, use the DROP AUDIT statement to remove the contents of the audit trail le. Run the CREATE AUDIT statement to start a new audit trail le, then back up the table. See the section Audit Trails in Chapter 3 for more information. 2. RECOVER TABLE checks that the audit trail and table-name have consistent record numbers for rows where changes have taken place. If RECOVER TABLE nds inconsistencies, it stops restoring the table. 3. You must own table-name or have DBA status to use the RECOVER TABLE statement.

Example
The following SQL statements give a template for the recovery of a table. They assume that your audit trail began from the last backup.
{restore table from last backup} RECOVER TABLE customer DROP AUDIT FOR customer CREATE AUDIT FOR customer IN "/dev/safe" {make a backup of the recovered table} INFORMIX-4GL Statement Syntax 7-179

RECOVER TABLE

Related Statements
CREATE AUDIT, DROP AUDIT

7-180

INFORMIX-4GL Statement Syntax

RENAME COLUMN

RENAME COLUMN
Overview
Use the RENAME COLUMN statement to change the name of a column.

Syntax
RENAME COLUMN table.oldcolumn TO newcolumn

Explanation
RENAME COLUMN are required keywords.

table oldcolumn
TO

is the required name of the table containing the column whose name is to be changed. is the name of the column to be renamed. is a required keyword. is the new name to be assigned to the column. The newcolumn must satisfy the requirements for an SQL identier, and cannot duplicate another column name in the table.

newcolumn

Notes
1. You can RENAME a column of a table only when you own the table, have DBA privilege, or have been granted ALTER permission. 2. The RENAME COLUMN statement cannot be rolled back.

Example
RENAME COLUMN customer.customer_num TO c_num

Related Statements
ALTER TABLE, CREATE TABLE, INSERT, DROP TABLE, RENAME TABLE

INFORMIX-4GL Statement Syntax

7-181

RENAME TABLE

RENAME TABLE
Overview
Use the RENAME TABLE statement to change the name of a table in the system catalogs.

Syntax
RENAME TABLE oldname TO newname

Explanation
RENAME TABLE

are required keywords. is the current name of the table to be renamed. is a required keyword. is the new name that you want to assign to the table.

oldname
TO

newname

Notes
1. In a non-MODE ANSI database, the newname identier must be unique among tables and synonyms. In a MODE ANSI database, it must be unique among tables and synonyms that you own. 2. You can RENAME a table only when you own the table, have DBA privilege, or have been granted ALTER permission on the table. 3. You can specify owner.oldname in a RENAME TABLE statement, but a compile-time error results if you specify owner.newname. 4. The RENAME TABLE statement cannot be rolled back.

7-182

INFORMIX-4GL Statement Syntax

RENAME TABLE

Example
This example moves the quantity column to the third place:
CREATE TABLE newtab (item_num order_num quantity stock_num manu_code total_price ) SMALLINT, INTEGER, SMALLINT, SMALLINT, CHAR(4), MONEY(8)

INSERT INTO newtab SELECT item_num, order_num, quantity, stock_num, manu_code, total_price FROM items DROP TABLE items RENAME TABLE newtab TO items

Related Statements
ALTER TABLE, CREATE TABLE, INSERT, DROP TABLE, RENAME COLUMN

INFORMIX-4GL Statement Syntax

7-183

REPORT

REPORT
Overview
Use the REPORT routine to provide the format specications for a report.

Syntax
REPORT report-name ( variable-list ) [ DEFINE-statement ] ... [ OUTPUT output-statement ...] [ ORDER [ EXTERNAL ] BY sort-list ] FORMAT format-statement ... 4gl-statement ... END REPORT

Explanation
REPORT

is a required keyword.

report-name is an INFORMIX-4GL identier. variable-list is a list of zero or more variables, separated by commas. DEFINE-statement is a DEFINE statement giving the data type for the variables in variable-list. OUTPUT is an optional keyword. output-statement is an output statement described in Chapter 5. ORDER BY are optional keywords. EXTERNAL is an optional keyword. sort-list is a list of one or more variables from those in variable-list. FORMAT is a required keyword. format-statement is a FORMAT statement described in Chapter 5. 4gl-statement is an arbitrary INFORMIX-4GL statement. END REPORT are required keywords that terminate the REPORT statement.

7-184

INFORMIX-4GL Statement Syntax

REPORT

Notes
1. If variable-list contains the name of a record, you must DEFINE the record in DEFINE-statement. Do not append the .* to the name of the record in variable-list. 2. See Chapter 5 for a discussion of the OUTPUT, ORDER BY, and FORMAT sections of the REPORT routine. 3. If INFORMIX-4GL statements occur in the control blocks of the FORMAT section, they are executed during the report-printing phase. If the data is sorted outside the report, report printing takes place with each OUTPUT TO REPORT statement. This is called a one-pass report. If the data is sorted inside the report, report printing takes place with the FINISH REPORT statement. This is called a two-pass report. If 4GL statements occur in the OUTPUT TO REPORT loop as well as in the report, INFORMIX-4GL alternately executes the 4GL statements in the OUTPUT TO REPORT loop and the 4GL statements in the report during a one-pass report. In contrast, INFORMIX-4GL repeatedly executes all the 4GL statements in the OUTPUT TO REPORT loop before executing the 4GL statements in the report during a two-pass report.

Example
The simplest report displays the output of a query:
DECLARE simp_curs CURSOR FOR SELECT * FROM CUSTOMER START REPORT simple FOREACH simp_curs INTO cust.* OUTPUT TO REPORT simple(cust.*) END FOREACH FINISH REPORT simple ... REPORT simple (x) DEFINE x RECORD LIKE customer.* FORMAT EVERY ROW END REPORT

Related Statements
FINISH REPORT, OUTPUT TO REPORT, START REPORT

INFORMIX-4GL Statement Syntax

7-185

RETURN

RETURN
Overview
Use the RETURN statement to leave a FUNCTION routine and to return values to the calling routine.

Syntax
RETURN [expr-list]

Explanation
RETURN

is a required keyword. is an optional list of one or more expressions, separated by commas.

expr-list

Notes
1. The RETURN statement can occur only within a FUNCTION routine and directs INFORMIX-4GL to exit the function and to return to the calling routine (MAIN, FUNCTION, or REPORT). 2. The expressions in expr-list must match in number and type the argument list in the RETURNING clause of the CALL statement.

Related Statement
FUNCTION

7-186

INFORMIX-4GL Statement Syntax

REVOKE

REVOKE
Overview
Use the REVOKE statement to remove another users access privileges for a database or table.

Syntax
REVOKE { tab-privilege ON table-name | db-privilege } FROM { PUBLIC | user-list}

Explanation
REVOKE

is a required keyword. is one or more of the following table-level access privileges, separated by commas: ALTER Adds or deletes columns or modies data types of columns DELETE Deletes rows INDEX Creates indexes INSERT Inserts rows SELECT Retrieves data UPDATE Changes column values ALL [PRIVILEGES] All of the above is a required keyword. is the name of the table for which you are revoking access privileges. is one of the following database-level access types: CONNECT allows access to database tables without permission to create permanent tables and indexes. RESOURCE allows access to database tables with permission to create permanent tables and indexes. DBA allows full database administrator privileges. is a required keyword.
INFORMIX-4GL Statement Syntax 7-187

tab-privilege

ON

table-name db-privilege

FROM

REVOKE

PUBLIC

is the keyword to revoke access privilege from all users. is a list of login names for the users whose access privilege you are revoking. You can enter one login name or a series of login names, separated by commas.

user-list

Notes
1. You cannot roll back the REVOKE statement. 2. You can revoke database-level access privileges only if you have DBA status. 3. You can revoke only those table-level access privileges that you have granted to another user. 4. You cannot revoke privileges from yourself. 5. Although you can grant UPDATE and SELECT privileges for specic columns, you cannot revoke these privileges column by column. If you revoke UPDATE or SELECT privileges from a user, INFORMIX-4GL automatically revokes all UPDATE and SELECT privileges that you have ever granted to that user for table-name. You can then re-grant privileges for specic columns. 6. Only a DBA recipient can revoke the DBA privilege from another recipient. If the database creator grants DBA privileges to another user, that person can revoke the DBA privilege from the database creator. 7. If you revoke the DBA or RESOURCE privilege from one or more users, they are left with the CONNECT privilege. To revoke all database privileges from users with DBA or RESOURCE status, you must revoke CONNECT as well as DBA or RESOURCE.

Examples
REVOKE ALL ON orders FROM PUBLIC REVOKE DELETE, UPDATE ON customer FROM jeff, judy REVOKE CONNECT FROM enid, felix

Related Statement
GRANT

7-188

INFORMIX-4GL Statement Syntax

ROLLBACK WORK

ROLLBACK WORK
Overview
Use the ROLLBACK WORK statement to undo all modications made to the database during the current transaction.

Syntax
ROLLBACK WORK

Explanation
ROLLBACK WORK

are required keywords.

Note
1. If you use the ROLLBACK WORK statement in a routine that is called by a WHENEVER statement, be sure to specify WHENEVER ERROR CONTINUE and WHENEVER WARNING CONTINUE before the ROLLBACK WORK statement. This will prevent the program from looping if the ROLLBACK WORK statement fails with an error or warning. 2. See the Transactions section in Chapter 3 for more information about transactions and the ROLLBACK WORK statement. 3. The ROLLBACK WORK statement releases all row and table locks. 4. The ROLLBACK WORK statement closes all open cursors except those DECLAREd WITH HOLD, although using it for this purpose is not recommended.

Related Statements
BEGIN WORK, COMMIT WORK

INFORMIX-4GL Statement Syntax

7-189

ROLLFORWARD DATABASE

ROLLFORWARD DATABASE
Overview
Use the ROLLFORWARD DATABASE statement to cause INFORMIX-4GL to apply the transactions registered in the transaction log le to a backup copy of your database, recovering all completed transactions.

Syntax
ROLLFORWARD DATABASE database-name

Explanation
ROLLFORWARD are required keywords. DATABASE database-name is the name of a database.

Notes
1. Immediately after you roll forward a database, it is in EXCLUSIVE mode, with no transactions. After the database is closed and reopened, it becomes accessible to other users, and transactions can resume. 2. See the section Transactions in Chapter 3 for more information.

Related Statements
BEGIN WORK, COMMIT WORK, START DATABASE, ROLLBACK WORK

7-190

INFORMIX-4GL Statement Syntax

RUN

RUN
Overview
Use the RUN statement to execute a system program.

Syntax
RUN command-line [ RETURNING integer-variable | WITHOUT WAITING ]

Explanation
is a required keyword. command-line is an expression that evaluates to a command line for your operating system. In particular, it may be a character string enclosed in quotation marks. RETURNING is an optional keyword. integer-variable is an INTEGER-type program variable that will receive the value returned by the program executed by the RUN statement. WITHOUT WAITING are optional keywords.
RUN

Note
RUN spawns a child process described by command-line. The WITHOUT WAITING option instructs INFORMIX-4GL to continue immediately to the next 4GL statement, while the RETURNING option instructs INFORMIX-4GL to await the return value before continuing to the next 4GL statement. If neither optional clause is present, INFORMIX-4GL waits until the child process is completed (and ignores the return code) before continuing to the next 4GL

statement.

Examples
RUN "date_script" RETURNING error_val RUN "isql -qr myscript" RUN charval[i]

INFORMIX-4GL Statement Syntax

7-191

SCROLL

SCROLL
Overview
Use the SCROLL statement to move rows of a screen record through a screen array.

Syntax
SCROLL { eld-list | screen-record. * } [ , . . . ] { UP | DOWN } [ BY integer ]

Explanation
SCROLL

is a required keyword. is a list of one or more screen eld names, separated by commas. is the name of a screen record. is an optional keyword indicating that the data on the screen should move upwards. is an optional keyword indicating that the data on the screen should move downwards. is an optional keyword. is an INTEGER constant or variable.

eld-list screen-record
UP DOWN BY

integer

Notes
1. The BY clause determines the number of lines upward or downward that the data will move. The default is 1. 2. It is the responsibility of the programmer to keep track of what data is left on the screen.

Example
SCROLL sc_item UP BY 2

Related Statements
DISPLAY ARRAY, INPUT ARRAY

7-192

INFORMIX-4GL Statement Syntax

SELECT

SELECT
Overview
Use the SELECT statement to query the current database. The SELECT statement can include up to eight clauses. Only the SELECT clause and the FROM clause are required.

Syntax
SELECT clause [ INTO clause ] FROM clause [ WHERE clause ] [ GROUP BY clause ] [ HAVING clause ] [ ORDER BY clause ] [ INTO TEMP clause ]

See The SELECT Statement section later in this chapter for detailed descriptions of these clauses.

INFORMIX-4GL Statement Syntax

7-193

SET EXPLAIN

SET EXPLAIN
Overview
Use the SET EXPLAIN statement to record how the query processor is accessing the database when executing a query.

Syntax
SET EXPLAIN { ON | OFF }

Explanation
SET EXPLAIN ON OFF

are required keywords. is a keyword to enable the EXPLAIN facility. is a keyword to disable the EXPLAIN facility. OFF is the default.

Notes
1. When you issue SET EXPLAIN ON, the access procedures of all subsequent queries are stored in the le sqexplain.out in your current directory. If sqexplain.out already exists, subsequent output is appended to it. SET EXPLAIN ON remains in effect until you issue SET EXPLAIN OFF, or the program ends. 2. SET EXPLAIN estimates the cost in CPU resources (a weighted sum of disk accesses and total rows processed), indicates the order of table access, and estimates the number of rows returned. For each table, SET EXPLAIN identies the type of access and the column(s) that serves as a lter, including whether the ltering is through an index. The following table-access types are available:
SEQUENTIAL SCAN INDEX PATH AUTOINDEX PATH

reads rows in sequence. scans one or more indexes. creates a temporary index.

3. The name of the owner precedes each table name in the output le.

7-194

INFORMIX-4GL Statement Syntax

SET EXPLAIN

Examples
The following example shows an sqexplain.out output le for a simple query and for a complex query from one table.
QUERY: -----select fname, lname, company from customer; Estimated Cost: 4 Estimated # of Rows Returned: 18 1) joe.customer: SEQUENTIAL SCAN

QUERY: -----select fname, lname, company from customer where company matches "Sport*" and customer_num between 110 and 115 order by lname; Estimated Cost: 3 Estimated # of Rows Returned: 1 Temporary Files Required For: Order By 1) joe.customer: INDEX PATH Filters: joe.customer.company MATCHES "Sport*" (1) Index Keys: customer_num Lower Index Filter: joe.customer.customer_num >= 110 Upper Index Filter: joe.customer.customer_num <= 115

INFORMIX-4GL Statement Syntax

7-195

SET EXPLAIN

The next example is from an sqexplain.out output le for a multiple-table query.

QUERY: -----select * from customer, orders, items where customer.customer_num = orders.customer_num and orders.order_num = items.order_num; Estimated Cost: 110 Estimated # of Rows Returned: 41 1) joe.orders: SEQUENTIAL SCAN 2) joe.customer: INDEX PATH (1) Index Keys: customer_num Lower Index Filter: joe.customer.customer_num = joe.orders.customer_num 3) joe.items: INDEX PATH (1) Index Keys: order_num Lower Index Filter: joe.items.order_num = joe.orders.order_num

Related Statements
ALTER INDEX, CREATE INDEX, SELECT, UPDATE STATISTICS

Note: Additional statistics are available for query processing when you use INFORMIX-OnLine as the database engine. As a result, estimates for the cost and the number of rows returned may be more precise under INFORMIX-OnLine.

7-196

INFORMIX-4GL Statement Syntax

SET LOCK MODE ( O )

SET LOCK MODE ( O )

Overview
Use the SET LOCK MODE statement to determine whether subsequent INFORMIX-4GL calls wait for a locked row to become unlocked.

Syntax
SET LOCK MODE TO [ NOT ] WAIT

Explanation
SET LOCK MODE TO NOT WAIT

are required keywords. is a required keyword. is an optional keyword. is a required keyword.

Notes
1. The TO NOT WAIT option causes INFORMIX-4GL to return an error if a statement attempts to alter or delete a row (or to SELECT a row FOR UPDATE) that another process has locked. This is the default situation; that is, if you have not issued a SET LOCK MODE statement previously. The NOT option is relevant, therefore, only when you have previously executed SET LOCK MODE TO WAIT and want to return to the default state. 2. The TO WAIT option causes INFORMIX-4GL to wait on an attempt to alter or delete a row (or to SELECT a row FOR UPDATE) that another process has locked until the locked row becomes unlocked. 3. Use the SET LOCK MODE TO WAIT statement with extreme caution. If the locking process fails and does not remove the lock, your statement could wait indenitely. 4. This feature is available only on systems that have record-level locking and applies only to row-level locking. Any attempt by another user to access a row in a table locked IN EXCLUSIVE MODE produces an error. 5. You can use the SET LOCK MODE statement only on systems that support kernel locking. An error is generated if you use the SET LOCK MODE statement with a system that does not support kernel locking.
INFORMIX-4GL Statement Syntax 7-197

SET LOCK MODE ( O )

Related Statement
LOCK TABLE

7-198

INFORMIX-4GL Statement Syntax

SLEEP

SLEEP
Overview
Use the SLEEP statement to cause the program to suspend operation for a period of time.

Syntax
SLEEP integer-expr

Explanation
SLEEP

is a required keyword. is an expression that evaluates to INTEGER type.

integer-expr

Note
The SLEEP statement causes the program to suspend operation for integerexpr seconds.

Example
SLEEP 4

INFORMIX-4GL Statement Syntax

7-199

START DATABASE

START DATABASE
Overview
Use the START DATABASE statement to start a new transaction log le.

Syntax
START DATABASE database-name WITH LOG IN "pathname" [ MODE ANSI ]

Explanation
START DATABASE are required keywords. database-name
WITH LOG IN

is the name of a database. are required keywords. is the full pathname, enclosed in quotation ( " ) marks, of the transaction log le. are optional keywords to convert the database to MODE ANSI.

pathname
MODE ANSI

Notes
1. The START DATABASE statement can perform these tasks:

Change the name of your transaction log le. Start recording transactions in a database that was created without
transactions.

Start a database that supports ANSI standards.

2. The START DATABASE statement opens the database in EXCLUSIVE mode. No users can access the database until you issue a CLOSE DATABASE statement. 3. After a database is started as MODE ANSI, you receive an error if you do not use the owner.object naming convention to refer to an object owned by another user. You must modify existing queries that reference a table, view, or synonym owned by another user to include the owner prex. See the section Owner Naming in Chapter 3 of this manual. 4. Do not use the BEGIN WORK statement in programs that access a MODE ANSI database. Since transactions are implicit in MODE ANSI, the BEGIN WORK statement is not needed.
7-200 INFORMIX-4GL Statement Syntax

START DATABASE

5. Singleton transactions do not exist in MODE ANSI. For a singleton statement, you must issue a COMMIT WORK statement to commit a transaction, or a ROLLBACK WORK statement to roll the database back to the last COMMIT WORK or ROLLBACK WORK statement. 6. See the section Transactions in Chapter 3 for more information on START DATABASE. See also the discussion of CREATE DATABASE earlier in this chapter for more information on MODE ANSI databases. 7. You can determine the type of database that a user selects by checking the return code from a DATABASE statement in the SQLCA.SQLAWARN character string. See the section SQLCA Record in Chapter 3 for more information. 8. You cannot remove MODE ANSI from a database. Once started as such, a database remains MODE ANSI.

Example
START DATABASE stores WITH LOG IN "/u/myname/stores.log" MODE ANSI

Related Statements
BEGIN WORK, COMMIT WORK, CREATE DATABASE, ROLLBACK WORK, ROLLFORWARD DATABASE

INFORMIX-4GL Statement Syntax

7-201

START REPORT

START REPORT
Overview
Use the START REPORT statement to begin processing a report.

Syntax
START REPORT report-name [ TO { lename | PRINTER | PIPE program } ]

Explanation
START REPORT are required keywords.

report-name
TO

is the identier of a report. is an optional keyword. is either a CHAR type variable or a quoted string constant containing the name of a system le. is an optional keyword. is an optional keyword. is either a CHAR variable or a string constant containing the command line for a system program.

lename
PRINTER PIPE

program

Notes
1. Usually, you will execute the START REPORT statement just before a loop in which you process the report data using the OUTPUT TO REPORT statement. 2. If you use the TO clause, INFORMIX-4GL ignores any REPORT TO statement in the OUTPUT section of report-name. 3. If you indicate lename, INFORMIX-4GL puts the report output there. 4. If you use the TO PRINTER option, INFORMIX-4GL sends the report output to your printer. The default printer command is lp or lpr; be sure to check with your system administrator. You can change the default by setting the DBPRINT environment variable. (See Appendix C.) 5. Use the TO PIPE option to pipe report output to program.

Related Statements
FINISH REPORT, OUTPUT TO REPORT, REPORT

7-202

INFORMIX-4GL Statement Syntax

UNLOAD

UNLOAD
Overview
Use the UNLOAD statement to write the data from a table to an ASCII le.

Syntax
UNLOAD TO "pathname" [ DELIMITER "char" ] SELECT-statement

Explanation
UNLOAD TO

are required keywords. is a quoted string or a character variable that evaluates to the pathname of the le in which to store the database table. is an optional keyword to indicate that the following char separates data elds in the le. is a single character that serves as the delimiter between elds. The char must appear in quotation marks. is a SELECT statement that retrieves the data to be written to a le.

pathname

DELIMITER

char
SELECT-statement

Notes
1. The data from each column in each row are separated from the data in the next column by the delimiter. INFORMIX-4GL uses as a delimiter the character included in the DELIMITER clause, if one is provided. If no DELIMITER clause appears in the statement, INFORMIX-4GL checks the setting in the DBDELIMITER environment variable, if it exists. The default delimiter is the vertical bar ( | = ASCII 124). If character data contains a delimiter character, INFORMIX-4GL automatically escapes it with a backslash to prevent interpretation as a special character. (Backslashes are automatically stripped when the eld is LOADed.) 2. As in a DECLARE statement for a SELECT cursor, the SELECT-statement can be either an unquoted SELECT statement, or the name of a string variable that contains a SELECT statement. 3. NULL columns have no characters between delimiters.
INFORMIX-4GL Statement Syntax 7-203

UNLOAD

4. Trailing blanks in CHARACTER data are clipped. Number data types have no leading blanks. 5. An INTEGER or SMALLINT zero is represented as 0 ; FLOAT, SMALLFLOAT, DECIMAL, and MONEY zeros are represented as 0.00. 6. MONEY values have no leading currency symbol. 7. DATE values are represented as mm/dd/yyyy, where mm is the month (January = 1, and so on), dd is the day, and yyyy is the year. 8. DATETIME and INTERVAL items are written in character form, showing only their eld digits and delimiters. No type specication or qualiers are output. INFORMIX-4GL uses the following pattern: yyyy-mm-dd hh:mi:ss.fff, omitting elds that are not part of the data. 9. You must have SELECT permission on all columns in the select-list of the SELECT statement to use the UNLOAD statement. 10. You cannot PREPARE an UNLOAD statement. 11. When you execute an UNLOAD statement, INFORMIX-4GL sets status to zero to indicate success, or to an error number to indicate failure. If an error occurs, the SQLCODE and SQLERRD[2] error codes are set, as described in Chapter 3. In any case, the value of SQLERRD[3] is set to the number of rows that UNLOAD copied to the le.

Example
UNLOAD TO "cust.out" DELIMITER ";" SELECT fname, lname, company, city FROM customer

Related Statements
LOAD, SELECT

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

7-204

INFORMIX-4GL Statement Syntax

UNLOCK TABLE

UNLOCK TABLE
Overview
Use the UNLOCK TABLE statement to unlock a table that you previously locked with the LOCK TABLE statement.

Syntax
UNLOCK TABLE table-name

Explanation
UNLOCK TABLE

are required keywords. is the name of the table you want to unlock.

table-name

Note
If the database has transactions, the UNLOCK TABLE statement can not be used and generates an error. All locks placed on the table are released when the COMMIT WORK or ROLLBACK WORK statement is processed.

Related Statement
LOCK TABLE

INFORMIX-4GL Statement Syntax

7-205

UPDATE

UPDATE
Overview
Use the UPDATE statement to change the values in one or more columns of one or more rows in a table.

Syntax
UPDATE table-name SET { column-name = expr [ , . . . ] | { ( column-list ) | [ table-name. ] * } = { ( expr-list) | record-name.* } } [ WHERE { condition | CURRENT OF cursor-name } ]

Explanation
UPDATE

is a required keyword. is the name of the table that contains the row(s) that you want to update. is a required keyword. is the name of a column you want to update. is any combination of column names, constants, program variables, arithmetic operators, or an SQL subquery that returns a single row of one value. is a list of the names of columns to be updated. refers to all columns in table-name. (You can substitute table-name.* if you prefer.) is a list of expressions that represent values corresponding to the columns in column-list or the columns represented by the asterisk notation. In expr-list, you can specify multiple values using a record name with the asterisk ( * ) or THRU notation. The list can also include an SQL subquery that returns a single row of multiple values. is the name of a program variable of type RECORD. is an optional keyword. is a condition for a standard WHERE clause made up of a search condition that compares the values in one column to the values in another column, to a program variable, or to a constant. (For further information, refer to the explanation of

table-name
SET

column-name expr

column-list * expr-list

record-name
WHERE

condition

7-206

INFORMIX-4GL Statement Syntax

UPDATE

WHERE clauses in the section The SELECT Statement at the end of this chapter.) CURRENT OF

are keywords. is the SQL identier of a previously DECLAREd cursor.

cursor-name

Notes
1. The expr can be a SELECT statement in parentheses that adheres to standard rules for subqueries. The SELECT statement can return no more than one value except when included in an expr-list. 2. You cannot use a SELECT statement that retrieves data from table-name. 3. The number of column names included in the column-list must equal the number of values produced in the expr-list. 4. Although the value returned by expr does not have to be of the same data type as column-name, it must be compatible. You can put only CHAR data into CHAR columns, and only numeric or character representations of numeric data into number columns. 5. If you use the CURRENT OF option in the WHERE clause, INFORMIX-4GL updates the current row of the active set and leaves the cursor on the same row. 6. If you do not specify any columns in the FOR UPDATE clause of a DECLARE statement, you can update any column in a subsequent UPDATE WHERE CURRENT OF statement. If you do specify one or more columns in the FOR UPDATE clause, you can update only those columns in a subsequent UPDATE WHERE CURRENT OF statement. When you specify the column names in the FOR UPDATE clause, INFORMIX-4GL can usually perform the updates more quickly. 7. SERIAL columns cannot be updated. If you want to use the [table-name].* notation and table-name contains a SERIAL column, you can only execute the following form of the UPDATE statement:
UPDATE table-name SET [table-name.]* = record-name.*

When INFORMIX-4GL executes this form of the UPDATE statement, it automatically skips any SERIAL column and the corresponding value in the expression list produced by record-name.*. 8. When you create a database with transactions that is not MODE ANSI, each UPDATE statement that you execute is treated as a single transaction, even if you do not use the BEGIN WORK and COMMIT WORK or ROLLBACK WORK statements.
INFORMIX-4GL Statement Syntax 7-207

UPDATE

9. Each row affected by an UPDATE statement within a transaction is locked for the duration of the transaction; therefore, a single UPDATE statement that affects a large number of rows locks those rows until the entire operation is completed. If the number of rows affected is very large, you can approach the limit that your operating system places on the maximum number of simultaneous locks. If this occurs, you may want to reduce the scope of the UPDATE statement, or lock the entire table before executing the statement. See the section Locking in Chapter 3 for a more detailed description of table-level and row-level locking in INFORMIX-4GL. 10. You cannot perform an UPDATE through a DECLAREd cursor that includes aggregate functions. The cursor can only specify simple column names. 11. The UNIQUE keyword cannot appear in a subquery within an UPDATE statement. Caution: If INFORMIX-4GL encounters an error while performing an UPDATE, the operation stops. Unless you have created the database with transactions, all database changes made up to the point where the error is encountered remain, but subsequent rows are not updated. A data conversion error is an example of an error that stops an UPDATE operation. Common data conversion errors include attempting to insert numeric data into a CHAR column, or attempting to insert numeric values that exceed the limits of the data type of the column. For example, you cannot insert the integer 123456 into a SMALLINT column. If you omit the WHERE clause, INFORMIX-4GL assumes that you want to update every row in the table.

7-208

INFORMIX-4GL Statement Syntax

UPDATE

Examples
UPDATE stock SET unit_price = unit_price * 1.04 WHERE manu_code = "HRO"

UPDATE customer SET * = p_customer.* WHERE customer_num = p_customer.customer_num

UPDATE customer SET (fname, company, address2) = ("Marie", "Maries Sports", "P. O. Box 3621") WHERE customer_num = 103

UPDATE table1 SET (col1, col2, col3) = ((select min (ship_charge), max (ship_charge) from orders), "07/01/1986") WHERE col4 = 1001

Related Statements
SELECT, DELETE, INSERT

INFORMIX-4GL Statement Syntax

7-209

UPDATE STATISTICS

UPDATE STATISTICS
Overview
Use the UPDATE STATISTICS statement to cause the number of rows in a table to be recorded in the systables catalog.

Syntax
UPDATE STATISTICS [ FOR TABLE table-name ]

Explanation
UPDATE STATISTICS are required keywords. FOR TABLE

are optional keywords you use when you want to update the statistics for a single table. is the name of the table for which you want the statistics updated.

table-name

Notes
1. UPDATE STATISTICS is effective only when there is a current database. 2. INFORMIX-4GL uses the data generated by UPDATE STATISTICS to optimize searching strategy. When you have modied a table extensively, use UPDATE STATISTICS to improve the efciency of queries. 3. INFORMIX-4GL does not update the statistics unless you execute the UPDATE STATISTICS statement. 4. If you omit the FOR TABLE clause, UPDATE STATISTICS updates all the tables in the current database.

Related Statement
SET EXPLAIN INFORMIX-OnLine supports additional functionality. Refer to the INFORMIXOnLine Programmers Manual for more information.

7-210

INFORMIX-4GL Statement Syntax

VALIDATE

VALIDATE
Overview
Use the VALIDATE statement to determine whether values in a list of variables conform to the allowed ranges of values in syscolval for a corresponding list of columns.

Syntax
VALIDATE variable-list LIKE column-list

Explanation
VALIDATE

is a required keyword. is a list of one or more variables, separated by commas. is a required keyword. is a list of column names, preceded by table names and separated by commas.

variable-list
LIKE

column-list

Notes
1. There must be as many entries in column-list as there are variables in variable-list. 2. You must use a table-name prex to designate the column names. 3. In a MODE ANSI database, the name of a table is qualied by the owner of the table (owner. table-name). You must specify owner when you refer to a table owned by another user. The use of the prex owner is optional in a non-MODE ANSI database. INFORMIX-4GL does check the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 for more information. 4. You can use the upscol utility to create and update the values in syscolval. (See the discussion of The upscol Utility in Appendix E.) 5. If the current database is not MODE ANSI, the upscol utility creates a single syscolval table that species acceptable values or ranges of values for any or all columns in the database. The VALIDATE statement compares variable-list with the limitations specied in this table.

INFORMIX-4GL Statement Syntax

7-211

VALIDATE

6. In a MODE ANSI database, each user of upscol creates an individual owner. syscolval table. When it executes the VALIDATE statement, INFORMIX-4GL compares each component of variable-list to the syscolval table that belongs to the owner of the corresponding table-name.column-name in column-list. (You can omit the owner prex from table-name if the user who compiled the current 4GL program is the owner of table-name.) If the owner. syscolval table does not exist, the VALIDATE statement takes no action. 7. If the values of the components of variable-list do not conform entirely with the INCLUDE values of syscolval, INFORMIX-4GL sets the status variable to a negative value. You must test the variables individually to detect the non-conforming component. 8. The column-list cannot include DATETIME or INTERVAL columns. 9. You can use the * notation in variable-list and column-list.

Examples
VALIDATE var1, var2, var3 LIKE tab1.col1, tab1.col2, tab1.col3 VALIDATE p_customer.* LIKE customer.*

Related Statement
INITIALIZE

7-212

INFORMIX-4GL Statement Syntax

WHENEVER

WHENEVER
Overview
Use the WHENEVER statement to trap errors and other exceptional conditions that result during the execution of other 4GL statements.

Syntax
WHENEVER { ERROR | WARNING | NOT FOUND } {GOTO [ : ] label | CALL function-name | CONTINUE | STOP }

Explanation
WHENEVER ERROR

is a required keyword. is a keyword to test for an error (status < 0) after each 4GL statement. Its synonym SQLERROR conforms to the ANSI standard for SQL syntax. is a keyword to test for a warning (SQLAWARN[1] is set to W) after each 4GL statement. Its synonym is SQLWARNING. are keywords to test whether a FETCH is attempted beyond the rst or last row in the active set, or if no more rows satisfy the current SELECT statement (status=100). is an optional keyword. Its synonym GO TO conforms to the ANSI standard for SQL syntax. is an optional prex to label, and conforms to the ANSI standard for SQL syntax. is a statement label to which program control transfers when the specied exceptional condition occurs. is an optional keyword. is the name of a function to which program control transfers when the exceptional condition occurs. is an optional keyword, instructing INFORMIX-4GL to take no action. You can use this option to turn off a previously specied option. is an optional keyword, instructing INFORMIX-4GL to exit from the program immediately.

WARNING NOT FOUND

GOTO

: label
CALL

function-name
CONTINUE

STOP

INFORMIX-4GL Statement Syntax

7-213

WHENEVER

Notes
1. The WHENEVER statement is shorthand for putting an IF statement after every SQL statement and form-related INFORMIX-4GL statement, and testing for an error, warning, or NOT FOUND condition. 2. In the default situation, INFORMIX-4GL tests for errors (not warnings) after every INFORMIX-4GL statement. The 4GL compiler sets the declared database (that is, the database specied in the DATABASE statement that precedes the MAIN program block or the rst FUNCTION or REPORT routine of the module) as the current database and determines whether it is MODE ANSI. If (at compile time) the database is MODE ANSI, the default for WHENEVER ERROR is CONTINUE. Otherwise, the default is STOP. No DATABASE or START DATABASE statement in a function has any effect on the WHENEVER ERROR default. 3. A program can include several WHENEVER statements. If they refer to the same exception condition (ERROR, WARNING, or NOT FOUND), the last one encountered takes precedence. 4. The scope of a WHENEVER statement is the le in which it occurs, and from its position in the le to the next WHENEVER statement for the same exception condition in the same le. The scope extends to the end of the le, if you do not specify more WHENEVER statements for the same exception condition. 5. INFORMIX-4GL provides useful information (like source-le line numbers where an error has occurred) when it terminates a program because of an error. You may want to allow errors to occur during program development and insert trapping at a later stage. 6. If the NOT FOUND condition (status=100) is returned, the open cursor is automatically closed. 7. The label or :label specied after the GOTO or GO TO keywords must be in the same routine (that is, the same FUNCTION, REPORT, or MAIN program block) as the WHENEVER statement. 8. Some errors cannot be trapped by the WHENEVER ERROR statement. Certain errors always terminate the program, and others result in action by INFORMIX-4GL prior to the action specied by WHENEVER. (If you also have the INFORMIX-4GL Interactive Debugger, however, you can examine the current execution stack and the values of program variables after any error that is not followed by a system crash.) 9. While both NOT FOUND and NOTFOUND indicate the same condition, they cannot be used interchangeably. Use NOTFOUND (a single word)
7-214 INFORMIX-4GL Statement Syntax

WHENEVER

with status, and use NOT FOUND (two words) with the WHENEVER statement.

Examples
The following statement executes a function called error_recovery if an error condition is detected:
WHENEVER ERROR CALL error_recovery

The next statement terminates program execution if a warning is issued:

WHENEVER WARNING STOP

In the following program fragment, the WHENEVER statement transfers control, after a NOT FOUND condition, to the statement whose label is missing: in the same routine. (The use of keywords and colons here conforms to the ANSI standard for SQL syntax.)
MAIN WHENEVER NOT FOUND GO TO :missing . . . LABEL missing: DISPLAY "No row was retrieved from the database." AT 12,1 . . . END MAIN

Related Statements
CALL, DEFER, FOREACH, GOTO, IF, LABEL

INFORMIX-4GL Statement Syntax

7-215

WHILE

WHILE
Overview
Use the WHILE statement to execute a group of statements while a condition is TRUE.

Syntax
WHILE Boolean-expr statement ... [ EXIT WHILE ] ... [ CONTINUE WHILE ] ... END WHILE

Explanation
WHILE

is a required keyword. is an expression that can be either true or false. is an INFORMIX-4GL statement (including another WHILE statement). is an optional statement. is an optional statement. are required keywords that terminate a WHILE statement.

Boolean-expr statement
EXIT WHILE CONTINUE WHILE END WHILE

Notes
1. The CONTINUE WHILE statement interrupts the sequence and causes the program control to return to the top of the sequence and to test the Boolean-expr. 2. The EXIT WHILE statement interrupts the sequence and causes the program control to jump to the rst statement following the END WHILE keywords. 3. If Boolean-expr is FALSE on entry to the WHILE statement, program control passes directly to the statement following END WHILE.

7-216

INFORMIX-4GL Statement Syntax

WHILE

Related Statements
CONTINUE, EXIT, FOR

INFORMIX-4GL Statement Syntax

7-217

The SELECT Statement

The SELECT Statement

Overview
Use the SELECT statement to query the current database. The SELECT statement can include the following eight clauses. Of these, only the SELECT clause and the FROM clause are required. If the INTO clause is present, it must precede the FROM clause.

Syntax
SELECT clause [ INTO clause ] FROM clause [ WHERE clause ] [ GROUP BY clause ] [ HAVING clause ] [ ORDER BY clause ] [ INTO TEMP clause ]

These clauses have the following syntax:

SELECT [ ALL | DISTINCT | UNIQUE ] select-list INTO variable-list FROM { table-name [ table-alias ] | OUTER table-name [ table-alias ] | OUTER ( table-expr ) } [ , . . . ] WHERE condition

A condition is a collection of one or more search conditions connected by the logical operators AND, OR, or NOT. A search condition can be any of the following three types: 1. Comparison condition a. expr rel-op expr b. expr [ NOT ] BETWEEN expr AND expr c. expr [ NOT ] IN ( value-list ) d. column-name [ NOT ] LIKE "string" [ ESCAPE "esc-char" ] e. column-name [ NOT ] MATCHES "string" [ ESCAPE "esc-char" ] f. column-name IS [ NOT ] NULL 2. Join condition (a comparison condition among columns of the joined tables)

7-218

INFORMIX-4GL Statement Syntax

The SELECT Statement

3. Condition with subquery a. expr rel-op { ALL | ANY | SOME } ( SELECT-statement ) b. expr [ NOT ] IN ( SELECT-statement ) c. [ NOT ] EXISTS ( SELECT-statement )
GROUP BY column-list HAVING condition ORDER BY column-name [ ASC | DESC ] [ , . . . ] INTO TEMP table-name

Explanation
The following pages explain each of the syntax elements. A few basic concepts are dened here. 1. An expression consists of a column name, a program variable, a constant, or any combination of these connected by the following arithmetic operators:
Operator + * / Operation addition subtraction multiplication division

Note: Unlike INFORMIX-4GL statements, SQL statements cannot contain expressions that use the exponentiation (**) or modulus ( mod ) operators. The result of the operation must make sense. For example, you cannot divide 16 by Jones. Column names in expressions must have an at sign ( @ ) in front of them if there is danger of confusion with program variables that have the same identier.
SQL has three functions that you can use wherever a constant can be used. TODAY always returns the system date. CURRENT returns the system date and the time of day. USER returns a string containing the login name of

the current user. The CURRENT function is described later in this chapter. The TODAY and USER functions are described in Chapter 3. An expression can also be one of the aggregate, date, datetime, or length functions. You cannot include both an aggregate function and a column

INFORMIX-4GL Statement Syntax

7-219

The SELECT Statement

in an expression. The functions that you can use in SQL statements are dened at the end of this chapter. A CHAR column can have subscripts so that only a portion of the column value is involved in the expression. The notation for subscripting a column is column-name[m, n], where you want the mth through the nth characters in the column, for m less than or equal to n. Here the brackets are literal characters, not conventional symbols to indicate an option. 2. A relational operator is one of the following:
Operator = != or < > > >= < <= Operation equal to not equal to greater than greater than or equal to less than less than or equal to

For CHAR expressions, greater than means after in the ASCII collating order, where lowercase letters are after uppercase letters, and both are after numerals. See Appendix H for the ASCII codes of all the characters. For DATE and DATETIME expressions, greater than means later in time.

Notes
1. The clauses of the SELECT statement are explained in detail on the following pages. Briey, SELECT names a list of columns or expressions to be retrieved, INTO names the program variables to receive the data, FROM names a list of tables, WHERE sets conditions on the rows, GROUP BY groups rows together, HAVING sets conditions on the groups, ORDER BY sequences the selected rows, and INTO TEMP puts the results into a temporary table. 2. If the SELECT statement returns no rows, INFORMIX-4GL returns a no rows found code (status = NOTFOUND = 100). See Chapter 3 for a full explanation. 3. If a SELECT statement returns more than one row or if it is dynamically dened, you must use a cursor to FETCH one row at a time (see Chapter 3). 4. It is sometimes helpful to think of the SELECT statement in the following way: When you list more than one table in the FROM clause, INFORMIX-4GL behaves as though it were creating a composite table that is the Cartesian product of all the tables in the FROM clause. That is, the rows of the new table are constructed by taking all the possible combinations of rows from
7-220 INFORMIX-4GL Statement Syntax

The SELECT Statement

all the tables listed in the FROM clause. If there is a WHERE clause, INFORMIX-4GL eliminates from this new table all rows that do not meet the conditions of the WHERE clause. This modied table is returned to the SELECT clause, where all columns not listed are eliminated. The resulting table is what the SELECT statement returns. 5. The SELECT statement cannot appear in a multi-statement PREPARE.

INFORMIX-4GL Statement Syntax

7-221

SELECT Clause

SELECT Clause
Overview
Use the SELECT clause to specify the data that you want to retrieve from one or more tables in a database.

Syntax
SELECT [ ALL | DISTINCT | UNIQUE ] select-list

Explanation
SELECT ALL

is a required keyword. is a keyword that causes INFORMIX-4GL to select all rows that satisfy the WHERE clause, without eliminating duplicates. This keyword is the default. is a keyword that causes INFORMIX-4GL to eliminate duplicate rows from the query results. is a keyword that is synonymous with DISTINCT. is a list of column names and/or expressions separated by commas. A column name must be unambiguous; use its table name as a prex if there can be confusion.

DISTINCT UNIQUE

select-list

Notes
1. If the SELECT statement does not include a WHERE clause, every row will be returned. 2. The DISTINCT or UNIQUE keyword can appear once in each level of a query or subquery. 3. You can use the asterisk (*) in the select-list to select all columns from all the tables and views in the FROM clause. You could produce the same result by listing every column name in the select-list. 4. To select all the columns from a single table or view, you can use the notation tablename.*. 5. You can supply a display label for the column name or an expression in the select-list by following the column name or expression with a legal identier. If you create a temporary table with the INTO TEMP clause, the
7-222 INFORMIX-4GL Statement Syntax

SELECT Clause

column names of the temporary table are the display labels, if they have been dened. 6. If you specify an aggregate function and a column in the select-list, the column must be used in the GROUP BY list (see GROUP BY Clause for further explanation).

Examples
The following examples use INTO, FROM, and WHERE clauses, whose syntax will be dened later. This example selects columns customer_num, lname, and city; the FROM clause indicates that these columns are taken from the customer table. The values returned are placed in the program variables cnum, lname, and town, respectively. Since lname is both a program variable name and a column name, the column identier is prexed with the at ( @ ) sign.
SELECT customer_num, @lname, city INTO cnum, lname, town FROM customer

The next statement counts the number of rows in orders in which the customer_num column contains the value 101. In other words, it counts the number of orders made by the customer whose identifying number is 101. The number is placed in the variable num.
SELECT COUNT(*) INTO num FROM orders WHERE customer_num = 101

The next statement computes the average of the total_price values in those rows of items that contain an order_num column equal to 1021.
SELECT AVG(total_price) FROM items WHERE order_num = 1021

The next example illustrates the use of display labels. It selects the sum of columns a and b from tablez and gives the sum the label abtotal. Similarly, the product of columns c and d is labeled cdprod.
SELECT a+b abtotal, c*d cdprod FROM tablez INTO TEMP x

INFORMIX-4GL Statement Syntax

7-223

INTO Clause

INTO Clause
Overview
Use the INTO clause to specify the program variables to receive the data retrieved by the SELECT statement.

Syntax
INTO variable-list

Explanation
INTO

is a required keyword. is a list of program variables that should agree in order and type with the corresponding columns or expressions in the select-list.

variable-list

Notes
1. If the SELECT statement stands alone (not in a DECLARE statement), it must be a singleton SELECT (returning exactly one row) and must have an INTO clause. 2. If the SELECT statement returns more than one row, you must use a cursor to FETCH the rows one at a time. (See Chapter 3.) You can put the INTO clause in the FETCH statement, rather than in the SELECT statement, but not in both. You can use the FOREACH statement in place of the FETCH statement. 3. If you use DECLARE to associate a SELECT statement with a cursor, the SELECT statement can specify individual elements as a constant but not as a variable of a program array. (FETCH or FOREACH statements can specify program array elements as constants or variables in their INTO clause.) 4. If the number of variables in variable-list differs from the number of items in the select-list, INFORMIX-4GL returns a warning by setting SQLCA. SQLAWARN [4] to W. The actual number of variables transferred is the lesser of the two numbers. 5. If possible, INFORMIX-4GL converts the data type of each selected item to match that of the receiving variable. If the conversion is not possible, an error occurs and a negative value is returned in status. In this case, the
7-224 INFORMIX-4GL Statement Syntax

INTO Clause

value in the program variable is unpredictable. See Chapter 2 for a discussion of data conversion. 6. You cannot PREPARE a query that has an INTO clause. (Instead, you can DECLARE a cursor to perform the query.)

Examples
The following are equivalent program fragments:
DECLARE q_curs CURSOR FOR SELECT @lname, @company INTO lname, company FROM customer OPEN q_curs FETCH q_curs DECLARE q_curs CURSOR FOR SELECT @lname, @company FROM customer OPEN q_curs FETCH q_curs INTO lname, company DECLARE q_curs CURSOR FOR SELECT @lname, @company FROM customer FOREACH q_curs INTO lname, company . . .

INFORMIX-4GL Statement Syntax

7-225

FROM Clause

FROM Clause
Overview
Use the FROM clause to specify the table(s) or views from which you want to select data.

Syntax
FROM { table-name [ table-alias ] | OUTER table-name [ table-alias ] | OUTER ( table-expr ) } [ , . . . ]

Explanation
FROM OUTER

is a required keyword. is an optional keyword. is the name or synonym of a table or view in which to search for data. is an optional alias for table-name. is one or more of the options in the preceding syntax, enclosed in parentheses (for example tab1, outer tab2).

table-name table-alias (table-expr)

Notes
1. Use the optional keyword OUTER to form outer joins. See the Outer Joins section in Chapter 3 and Appendix G, Outer Joins, for a discussion of this syntax. 2. In a database created as MODE ANSI, the name of a table or view is qualied by the username of the owner (owner.table-name). You must specify owner when you refer to a table or view owned by another user. The use of the prex owner is optional in a database that is not MODE ANSI. INFORMIX-4GL checks the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 of this manual. 3. You can specify an alias for a table name by following the table name with a space and an SQL identier. This feature is especially useful when performing self-joins. (See the WHERE Clause section of this chapter.)

7-226

INFORMIX-4GL Statement Syntax

FROM Clause

4. The table-alias that you can specify in a FROM clause is distinct from the alias for a table that is sometimes required in the TABLES section of a form specication le. An alias that you dene in a form can appear in 4GL screen interaction statements that reference screen elds but cannot appear in a SELECT statement. (See Chapter 4.)

Examples
The following example selects customers who have placed orders.
SELECT fname, lname, order_num FROM customer, orders WHERE customer.customer_num = orders.customer_num

The following example selects all customers whether or not they have placed orders.
SELECT fname, lname, order_num FROM customer, OUTER orders WHERE customer.customer_num = orders.customer_num

INFORMIX-4GL Statement Syntax

7-227

WHERE Clause

WHERE Clause
Overview
Use the WHERE clause to specify search criteria and join conditions on the data to be selected.

Syntax
WHERE condition

Explanation
WHERE

is a required keyword. is a collection of one or more search conditions, optionally connected by the logical operators AND, OR, or NOT. A search condition can be any of the following:

condition

Comparison condition Join condition Condition with subquery

Comparison Condition
A comparison condition can have one of the following forms: a. expr rel-op expr b. expr [ NOT ] BETWEEN expr AND expr c. expr [ NOT ] IN ( value-list ) d. column-name [ NOT ] LIKE "string" [ ESCAPE "esc-char" ] e. column-name [ NOT ] MATCHES "string" [ ESCAPE "esc-char" ] f. column-name IS [ NOT ] NULL These forms are explained in the following pages. Any one of these conditions can be preceded by the keyword NOT, in which case the row is selected only if the condition that NOT qualies is FALSE.

Syntax
expr rel-op expr

7-228

INFORMIX-4GL Statement Syntax

WHERE Clause

Explanation
expr rel-op is an expression. is a relational operator.

Examples
SELECT fname, lname, company FROM customer WHERE city[1,3] = "San" SELECT order_num, company FROM orders o, customer c WHERE o.order_date > "6/12/86" AND o.customer_num = c.customer_num

If a column value is NULL in a given row, the WHERE clause will not locate that row if you use relational operators. For example, if paid_date has a NULL value, you cannot use either statement (a) or (b) to retrieve that row:
--(a) SELECT customer_num, order_date FROM orders WHERE paid_date = "" --(b) SELECT customer_num, order_date FROM orders WHERE NOT paid_date != ""

You must use the syntax that follows:

SELECT customer_num, order_date FROM orders WHERE paid_date IS NULL

Syntax
expr [ NOT ] BETWEEN expr AND expr

Explanation
expr
NOT BETWEEN

is an expression. is a keyword that indicates that the expression to the left lies outside the range. is a keyword that indicates that the value of the expression to its left lies in the inclusive range of the values of the two expressions to its right.
INFORMIX-4GL Statement Syntax 7-229

WHERE Clause

AND

is a required keyword.

Examples
SELECT stock_num, manu_code FROM stock WHERE unit_price BETWEEN loprice AND hiprice SELECT UNIQUE customer_num, stock_num, manu_code FROM orders, items WHERE order_date BETWEEN "6/1/86" AND "9/7/89" AND orders.order_num = items.order_num SELECT fname, lname FROM customer WHERE zipcode NOT BETWEEN "94100" AND "94199"

Syntax
expr [ NOT ] IN ( value-list )

Explanation
expr
NOT IN

is an expression. is an optional keyword. is a required keyword. is a list of values (enclosed in parentheses).

(value-list)

Notes
1. The search condition is satised when the expression to the left is included in the list of items. The NOT option produces a search condition that is satised when expr is not in the list of items. 2. The value-list can contain program variables, constants, or the special keyword constants TODAY, CURRENT, and USER. 3. TODAY is evaluated at execution time. CURRENT is evaluated when a cursor is opened, or when the query is executed if it is a singleton select.

7-230

INFORMIX-4GL Statement Syntax

WHERE Clause

Examples
SELECT lname, fname, company FROM customer WHERE state IN ("CA", "WA", "OR") SELECT item_num, total_price INTO inum, tprice FROM items WHERE manu_code IN ("HRO", "HSK")

Syntax
column-name [ NOT ] LIKE "string" [ ESCAPE "escape-character" ]

Explanation
column-name
NOT LIKE

is the name of a column. is an optional keyword. is a required keyword. is a pattern of characters enclosed in quotation marks. is an optional keyword.

string
ESCAPE

escape-character is a single character enclosed in quotation marks.

Notes
1. The search condition is successful when the value of the column on the left matches the pattern specied by string. You can use wildcard characters in place of other characters in the string: % _ A percent sign matches zero or more characters. An underscore matches any single character.

2. The NOT option makes the search condition successful when the column on the left does not match the pattern specied by string. 3. The purpose of the ESCAPE clause is to permit the specication of an underscore ( _ ) or the percent sign ( % ) in string, and to avoid their interpretation as wildcards. If z is the escape-character, then the characters z_ in a string stand for the character _ (not the wildcard). Similarly, z% in the string stands for the character % (not the wildcard). Finally, the characters zz in the string stand for the single character z.

INFORMIX-4GL Statement Syntax

7-231

WHERE Clause

4. You can only use the double quote ( " ) within string to match a literal quote; you cannot use the ESCAPE keyword. Similarly, you cannot use the quote character as the ESCAPE character in matching any other pattern.

Examples
SELECT fname, lname FROM customer WHERE lname LIKE "%son"

nds every customer representative whose last name ends in son.

SELECT stock_num, manu_code, unit_price FROM stock WHERE description LIKE "%ball%"

obtains stock number, manufacturers code, and unit price for all stock items with ball anywhere in their description.
SELECT * FROM customer WHERE company LIKE "%z_%" ESCAPE "z"

retrieves rows from the customer table where the company column value includes the underscore character.

Syntax
column-name [ NOT ] MATCHES "string" [ ESCAPE "escape-character" ]

Explanation
column-name
NOT MATCHES

is the name of a column. is an optional keyword. is a required keyword. is a pattern of characters enclosed in quotation marks. is an optional keyword.

string
ESCAPE

escape-character is a single character enclosed in quotation marks.

Notes
1. The search condition is successful when the value of the column on the left matches the pattern specied by string. You can use the following wildcard characters in place of other characters in the string: * ?
7-232

matches zero or more characters matches any single character

INFORMIX-4GL Statement Syntax

WHERE Clause

[...]

matches any of the enclosed characters, including character ranges as in [a-z]. A caret ( ^ ) as the rst character within the brackets matches any character that is not listed. Here [^abc] matches any character that is not a, b, or c. escapes special signicance of the next character (used to match * or ? by writing \* or \?)

2. The NOT option makes the search condition successful when the column on the left does not match the pattern specied by string. 3. The MATCHES comparison is an Informix Software extension to retain compatibility with earlier versions of Informix products. 4. Values used in a MATCHES search must be character strings. 5. The purpose of the ESCAPE clause is to permit the specication of a question mark ( ? ), an asterisk ( * ), the backslash ( \ ), and left or right bracket ( [ ] ), in string and to avoid their interpretation as wildcards. If z is the escape character, then the characters z? in a string stand for the character ? (not the wildcard). Similarly, z* in the string stands for the character * (not the wildcard). Finally, the characters zz in the string stand for the single character z (same as \z). 6. You can only use the double quote ( " ) within string to match a literal quote; you cannot use the ESCAPE keyword. Similarly, you cannot use the quote character as the ESCAPE character in matching any other pattern.

Examples
SELECT fname, lname FROM customer WHERE lname MATCHES "Richard*"

selects rows in which the rst seven letters of the last name are Richard (thus matching Richard, Richards, Richardson, and any others).
SELECT customer_num, company FROM customer WHERE city MATCHES "[A-J]*"

provides the customer number and company name for all customers in cities that start with the letters A through J.
SELECT * FROM customer WHERE company MATCHES "*z?*" ESCAPE "z"

retrieves rows from the customer table, where the value in the company column includes the question mark.

INFORMIX-4GL Statement Syntax

7-233

WHERE Clause

Syntax
column-name IS [ NOT ] NULL

Explanation
column-name
IS NULL NOT

is the name of a column. are required keywords. is an optional keyword.

Examples
SELECT order_num, customer_num FROM orders WHERE paid_date IS NULL

lists those order numbers and customer numbers where the order has not been paid. You can link any number of the above-described conditions together using the logical operators AND or OR. For example:
SELECT order_num, total_price FROM items WHERE total_price > loprice AND manu_code LIKE "H%" SELECT lname, customer_num FROM customer WHERE zipcode BETWEEN "93500" AND "95700" OR state NOT IN ("CA", "WA", "OR")

Join Conditions Overview

You join two tables when you create a relationship in the WHERE clause between at least one column from one table and at least one column from another table. The effect of the join is to create a temporary composite table in which each pair of rows (one from each table) satisfying the join condition is linked together to form a single row.

7-234

INFORMIX-4GL Statement Syntax

WHERE Clause

Syntax
The critical elements of a SELECT statement with a join between two tables or views table1 and table2 follow:
SELECT clause FROM table1, table2 WHERE condition

Explanation
SELECT clause is any valid SELECT clause involving columns from table1 or

table2.
FROM

is a required keyword. is the name or synonym of one of the tables or views in the join. is the name or synonym of the other table or view in the join. is a required keyword. is any of the comparison conditions that involves columns from both table1 and table2.

table1 table2
WHERE

condition

Notes
1. When columns from different tables have the same name, you must distinguish them by prexing the table identier and a period, in the format table.column. 2. In a database created as MODE ANSI, the name of a table is qualied by the owner of the table (owner. table-name). You must specify owner when you refer to a table owned by another user. The use of the prex owner is optional in a non-MODE ANSI database. INFORMIX-4GL checks the accuracy of owner, however, if you include it in a statement. See the section Owner Naming in Chapter 3 of this manual. 3. A multiple join is a join of more than two tables. Its structure is similar to that shown previously, except that you have a join condition for more than one pair of tables in the FROM clause. 4. You can also join a table to itself in a self-join. To do so, you must list the table name twice in the FROM clause, assigning it two different aliases. Use the aliases to refer to each of the two tables in the WHERE clause. 5. An outer join occurs when every row from table1 is taken, whether or not the join condition is met. If the join condition is not met, the columns from table2 in the select-list are set to NULL values. You indicate an outer join by inserting the keyword OUTER before table2.
INFORMIX-4GL Statement Syntax 7-235

WHERE Clause

Examples
This example species a two-table join:
SELECT order_num, lname, fname FROM customer, orders WHERE customer.customer_num = orders.customer_num

The query results list the order number and rst and last names of the customers representative for each order. This example species a multiple-table join:
SELECT UNIQUE company, stock_num, manu_code FROM customer c, orders o, items i WHERE c.customer_num = o.customer_num and o.order_num = i.order_num

This query yields the company name of the customer who ordered an item identied with the stock number and manufacturer code. This example species a self-join:
SELECT x.stock_num, x.manu_code, y.stock_num, y.manu_code FROM stock x, stock y WHERE x.unit_price > 2.5 * y.unit_price

This query nds pairs of stock items whose unit prices differ by a factor greater than two and one-half. Here x and y are each aliases for the stock table. This example species an outer join:
SELECT company, order_num FROM customer c, OUTER orders o WHERE c.customer_num = o.customer_num

This query lists all the customers company names and order numbers, if the customer has placed an order. If not, the company name will still be listed. See the Outer Joins section in Chapter 3 and Appendix G for information about outer joins.

7-236

INFORMIX-4GL Statement Syntax

WHERE Clause

Subquery Overview
The search condition in a SELECT statement can also perform these tasks:

Compare an expression to the result of another SELECT statement Determine whether an expression is included in the results of another
SELECT statement

Ask whether any rows are selected by another SELECT statement

SELECT statements within a WHERE clause are called subqueries. A subquery can return a single value, no values, or a set of values. If a subquery returns a value, it must return only a single row or column. If the subquery does not return a value (for example, with the EXISTS keyword), any number of rows and columns can be returned. A subquery cannot contain an ORDER BY clause.

The subquery can depend on whether the current row is being evaluated by the outer SELECT statement (correlated subqueries).

Syntax
WHERE expr rel-op { ALL | [ ANY | SOME ] } ( SELECT-statement ) WHERE expr [ NOT ] IN ( SELECT-statement ) WHERE [ NOT ] EXISTS ( SELECT-statement )

Explanation
WHERE

is a required keyword. is an expression. is a relational operator. is a keyword to specify that the subquery can return zero, one, or more values, and that the search condition is TRUE if the comparison is TRUE for each of the values returned. If the subquery returns no value, the search condition is TRUE. is a keyword to specify that the subquery can return zero, one, or more values and that the search condition is TRUE if the comparison is TRUE for at least one of the values returned. If the subquery returns no value, the search condition is FALSE. is a synonym for ANY.
INFORMIX-4GL Statement Syntax 7-237

expr rel-op
ALL

ANY

SOME

WHERE Clause

IN EXISTS

is a keyword that asks whether expr is among the values returned by the following SELECT-statement. is a keyword that asks whether any rows are returned by the following SELECT-statement. The search condition is TRUE if the subquery returns one or more rows. is an optional keyword that reverses the truth value of the search condition. Rows are selected if the WHERE condition is FALSE.

NOT

Notes
1. You can omit the keywords ANY and ALL in a comparison if you know that the subquery will return exactly one value. In this case, the search condition is TRUE if the comparison is TRUE for the expression and the value returned by the subquery. The status will be set to a negative number if the subquery returns other than a single value. 2. The specication expr IN ( SELECT-statement ) is equivalent to expr = ANY ( SELECT-statement ). 3. The specication expr NOT IN ( SELECT-statement ) is equivalent to expr ! = ALL ( SELECT-statement ).

Examples
SELECT order_num FROM items WHERE stock_num = 9 AND quantity = (SELECT MAX(quantity) FROM items WHERE stock_num = 9)

This subquery returns a single value (the maximum number of volleyball nets ordered) to the outer-level query. The entire SELECT statement lists the order numbers for orders that include the maximum number of volleyball nets.
SELECT UNIQUE order_num FROM items WHERE total_price > ALL (SELECT total_price FROM items WHERE order_num = 1011)

7-238

INFORMIX-4GL Statement Syntax

WHERE Clause

This query lists the order numbers of all orders containing an item whose total price is greater than the total price on all the items in order number 1011.
SELECT UNIQUE customer_num FROM orders WHERE order_num NOT IN (SELECT order_num FROM items WHERE stock_num = 1)

This query lists all customer numbers of customers who have placed orders that do not include baseball gloves (stock_num = 1).
SELECT order_num, stock_num, manu_code, total_price FROM items x WHERE total_price > (SELECT 2 * MIN(total_price) FROM items WHERE order_num = x.order_num)

This query (using a correlated subquery) lists all items whose total price is at least twice the minimum total price for all items on the same order.

INFORMIX-4GL Statement Syntax

7-239

GROUP BY Clause

GROUP BY Clause
Overview
Use the GROUP BY clause to produce a single row of results for each group. A group is a set of rows having the same values for each column listed.

Syntax
GROUP BY group-list

Explanation
GROUP BY

are required keywords. is a column name or a list of column names, separated by commas, that determines the group. The query result contains a single row for each set of rows that satises the WHERE clause and contains a unique value or set of values in the column or columns indicated by group-list.

group-list

Notes
1. Using a GROUP BY clause restricts what you can enter in the SELECT clause. The select-list can include aggregate functions for any column and/or the name of any column that you also list in the GROUP BY clause. You cannot, however, list any column in the select-list that you do not also list in group-list. 2. The SELECT list can contain expressions involving GROUP BY columns. 3. In the place of column names in group-list, you can enter one or more integers that refer to the position of items in the select-list. 4. NULL values are considered identical when evaluated within a GROUP BY clause. 5. You can GROUP BY up to eight columns.

Examples
SELECT order_num, COUNT(*), SUM(total_price) FROM items GROUP BY order_num

7-240

INFORMIX-4GL Statement Syntax

GROUP BY Clause

obtains the number of items and total price of all items for each order.
SELECT order_num, COUNT(*), SUM(total_price) FROM items GROUP BY 1

returns the same information as the previous example.

INFORMIX-4GL Statement Syntax

7-241

HAVING Clause

HAVING Clause
Overview
Use the HAVING clause to apply one or more qualifying conditions to groups.

Syntax
HAVING condition

Explanation
HAVING

is a required keyword. is a condition, as if dened for a WHERE clause.

condition

Notes
1. Each condition compares one column or aggregate property of the group either with another aggregate property of the group or with a constant. 2. The HAVING clause generally complements a GROUP BY clause. If you use HAVING without GROUP BY, the HAVING clause applies to all rows that satisfy the WHERE clause. Without a GROUP BY clause, all rows that satisfy the WHERE clause make up a single group. 3. You can use the HAVING clause to place conditions on the GROUP BY column values, as well as on aggregate values.

Example
SELECT order_num, AVG(total_price) FROM items GROUP BY order_num HAVING COUNT(*) > 2

This query returns the average total price per item on all orders that have more than two items.

7-242

INFORMIX-4GL Statement Syntax

ORDER BY Clause

ORDER BY Clause
Overview
Use the ORDER BY clause to sort query results by the values contained in one or more columns. You can sort only by a column that you specify in the SELECT clause.

Syntax
ORDER BY column-name [ ASC | DESC ] [ , . . . ]

Explanation
ORDER BY

are required keywords. is the name of a column by which you want to sort the query results. is a keyword that species that the results should be in ascending order (smallest value rst, largest last). ASC is the default. is a keyword that species that the results should be in descending order (largest value rst).

column-name
ASC

DESC

Notes
1. You can only ORDER BY columns that are named explicitly or implicitly in the select-list. 2. You can ORDER BY up to eight columns. 3. The total length of the data in the columns included in the ORDER BY clause cannot be greater than 120 bytes. 4. In the place of column names, you can enter one or more integers that refer to the position of items in the select-list. In this way, you can ORDER BY an expression. 5. You cannot use a DECLARE statement with a FOR UPDATE clause to associate a cursor with a SELECT statement that has an ORDER BY clause.

INFORMIX-4GL Statement Syntax

7-243

ORDER BY Clause

Examples
CORRECT: SELECT order_date, ship_date FROM orders ORDER BY order_date SELECT * FROM orders ORDER BY order_date SELECT order_date, ship_date FROM orders ORDER BY customer_num

CORRECT:

INCORRECT:

In the rst two examples, order_date is either explicitly or implicitly listed in the select-list. In the third example, even though the column customer_num is in the orders table, it was not contained in the select-list. The query in the next example
SELECT customer_num, fname, lname, company FROM customer ORDER BY 3, 2

performs a nested sort. The rst level of sorting is based on the lname column, and the second level is based on the fname column.

7-244

INFORMIX-4GL Statement Syntax

INTO TEMP Clause

INTO TEMP Clause

Overview
Use the INTO TEMP clause to create a temporary table that contains the query results. The temporary table disappears when your program ends.

Syntax
INTO TEMP table-name [ WITH NO LOG ]

Explanation
INTO TEMP

are required keywords. is the SQL identier that you assign to the temporary table. tables.

table-name

WITH NO LOG are optional keywords to prevent logging of temporary

Notes
1. You will save time if you use a temporary table when the same query results are required several times. 2. An INTO TEMP clause in a SELECT statement often gives you clearer and more easily understood statements. 3. The column names of the temporary table are those named in the selectlist. If you list a display label for a column or expression, the column name in the temporary table is the display label. 4. No indexes are associated with table-name. 5. Do not use an INTO clause with the INTO TEMP clause. If you do, no results will be returned to the program variables, and status will be set to a negative value. 6. The temporary table persists until you exit from your 4GL program or issue the DROP TABLE table-name statement. 7. The keywords WITH NO LOG prevent INFORMIX-4GL from including in the transaction log operations on temporary tables. You can use this option to reduce the overhead of transaction logging.

INFORMIX-4GL Statement Syntax

7-245

UNION Operator

UNION Operator
Overview
The UNION operator is a keyword placed between two SELECT statements, to let you combine the queries into a single query.

Syntax
SELECT-statement UNION [ ALL ] SELECT-statement [ UNION [ ALL ] SELECT-statement . . . ]

Explanation
UNION ALL

is a keyword that selects all rows from both queries, removes duplicates, and returns what is left. is an optional keyword that leaves the duplicates.

Notes
1. You can place the UNION operator between each member of a sequence of more than two queries. 2. It is possible to write single queries that are equivalent to the compound queries constructed using the UNION operator. The advantage of the UNION operator is that it makes the process easier. 3. There are restrictions on the queries that you can connect with UNION operators.

The number of the items in the select-list of each query must be the
same, and corresponding items in each select-list must have identical data types.

Corresponding items need not have the same identier.

7-246

INFORMIX-4GL Statement Syntax

UNION Operator

You cannot use an INTO statement in a query unless you are sure that
the compound query will return exactly one row and you are not using a cursor. In this rare case, the INTO clause must be in the rst SELECT statement.

If you use an ORDER BY clause, it must follow the last SELECT statement, and you must refer by integer, not by identier, to the item to be ordered. Ordering takes place after the set operation is complete. 4. UNION operators cannot occur inside a subquery and cannot be used in the denition of a view. 5. The column names (or display labels) of the resulting table are the same as those from the rst SELECT statement. 6. You can put the results of a UNION into a temporary table by putting an INTO TEMP clause in the nal SELECT statement.

Example
The following example selects those items (identied by a stock number and a manufacturing code) that have a unit price of less than $100.00 or that have been ordered in quantities greater than three.
SELECT DISTINCT stock_num, manu_code FROM stock WHERE unit_price < 100.00 UNION SELECT stock_num, manu_code, FROM items WHERE quantity > 3 ORDER BY 1

INFORMIX-4GL Statement Syntax

7-247

Functions in SQL Statements

Functions in SQL Statements

You can use the aggregate, length, date, and datetime functions anywhere in an SQL expression that a constant can appear. The following functions are available:
Aggregate Functions COUNT(*) SUM( ) AVG( ) MAX( ) MIN( ) Length Functions LENGTH( ) Date Functions DATE( ) DAY( ) MDY( ) MONTH( ) WEEKDAY( ) YEAR( ) Datetime Functions CURRENT EXTEND( )

These functions are dened on the pages that follow. You can also use the TODAY and USER functions that are described in Chapter 2 and Chapter 3 of this manual. Except for CURRENT, DATE( ), and MDY( ), all the date and datetime functions can accept both DATE and DATETIME values as arguments.

7-248

INFORMIX-4GL Statement Syntax

Aggregate Functions

Aggregate Functions
Overview
The aggregate functions take on values that depend on the set of rows returned by the WHERE clause of a SELECT statement. In the absence of a WHERE clause, the aggregate functions take on values that depend on all the rows formed by the FROM clause.
Syntax COUNT (*) COUNT ( DISTINCT x) Function

returns the number of rows that satisfy the WHERE clause. returns the number of different values in column x from rows that satisfy the WHERE clause. returns the sum of all values in column x from rows that satisfy the WHERE clause. You can apply SUM only to number columns. The default is ALL. If you use the keyword DISTINCT, the sum is only over distinct values in column x. returns the average of all values in column x from rows that satisfy the WHERE clause. You can apply AVG only to number columns. The default is ALL. If you use the keyword DISTINCT, the average (mean) is only over the distinct values in column x. returns the largest value in column x from a row that satises the WHERE clause. Default is ALL. returns the lowest value in column x from a row that satises the WHERE clause. Default is ALL.

SUM ( [ ALL | DISTINCT ] x)

AVG ( [ ALL | DISTINCT ] x)

MAX ( [ ALL | DISTINCT ] x)

MIN ( [ ALL | DISTINCT ] x)

Notes
1. In the functions SUM(x), AVG(x), MAX(x), and MIN(x), x can be an expression instead of a column name. If x is an expression, the function is evaluated over the values of the expression as computed for each row that

INFORMIX-4GL Statement Syntax

7-249

Aggregate Functions

satises the WHERE clause. The expression can not contain another aggregate function. 2. Both the COUNT(x) function and the keyword DISTINCT can only be used with column names, not with expressions. 3. You can use the keyword DISTINCT only once in each level of a query or subquery. Use DISTINCT to disregard duplicate query results or to eliminate duplicates from the argument of an aggregate function. 4. Specifying DISTINCT in a MIN or MAX function has no effect on the value returned by the function. 5. You can use the keyword UNIQUE as a synonym for DISTINCT. 6. Aggregate functions handle NULL values in these ways:

COUNT(DISTINCT x), AVG (x), SUM (x), MAX (x), and MIN (x) ignore rows with NULL values for x and return the appropriate values based on the rest of the rows.

If x contains only NULL values, however, then the function COUNT

(DISTINCT x ) returns zero, and the other aggregate functions return NULL for that column.

COUNT(*) counts all rows, even if the value of every column in the row is NULL.

Examples
If a query selects seven rows in which the set of values in column x is
{ 2, 2, 2, 3, 3, 4, NULL }

then COUNT (*) returns 7, and COUNT ( DISTINCT x ) returns 3. For these values, MAX (x) returns 4, and MIN (x) returns 2.

7-250

INFORMIX-4GL Statement Syntax

LENGTH( )

LENGTH( )
Overview
The LENGTH function returns the clipped length of a character column or variable.

Syntax
LENGTH ( string )

Explanation
string is a character variable, string constant, or the name of a column that contains character data.

Note
LENGTH allows only one argument. You can, however, combine LENGTH val-

ues through an expression. (See the example.)

Example
SELECT customer_num, LENGTH(fname) + LENGTH(lname), LENGTH("How many bytes is this?") FROM customer WHERE LENGTH(company) > 10

Note: INFORMIX-OnLine supports additional data types. Refer to the INFORMIX-OnLine Programmers Manual for more information.

INFORMIX-4GL Statement Syntax

7-251

DATE( )

DATE( )
Overview
The DATE( ) function returns a type DATE value, corresponding to the expression with which you call it.

Syntax
DATE ( expr )

Explanation
DATE

is a required keyword. is a required expression that can be converted to a type DATE value.

expr

Note
The expr is usually of type CHAR, DATETIME, or INTEGER.

Example
The following example uses DATE( ) to convert a string to a date.
WHERE end_date > DATE("12/13/1989")

7-252

INFORMIX-4GL Statement Syntax

DAY( )

DAY( )
Overview
The DAY( ) function returns an integer that represents the day of the month, when you call it with a type DATE or DATETIME argument.

Syntax
DAY ( time-expr )

Explanation
DAY

is a required keyword.

time-expr is a required expression whose value is of type DATE or DATETIME.

Example
This example uses the DAY ( ) function with the CURRENT function to compare column values to the current day of the month.
WHERE DAY(ord_date) > DAY(CURRENT)

INFORMIX-4GL Statement Syntax

7-253

MDY( )

MDY( )
Overview
The MDY( ) function returns a type DATE value when you call it with three expressions that evaluate to integers representing the month, day of the month, and year.

Syntax
MDY ( expr1, expr2, expr3 )

Explanation
MDY

is a required keyword. is an expression that evaluates to an integer representing the number of the month (1-12). is an expression that evaluates to an integer representing the number of the day of the month (1-28, 29, 30, or 31, depending on the month). is an expression that evaluates to a four-digit integer representing the year.

expr1 expr2

expr3

Notes
The value of expr3 cannot be the abbreviation for the year. For example, 89 is a year in the rst century.

7-254

INFORMIX-4GL Statement Syntax

MONTH( )

MONTH( )
Overview
The MONTH( ) function returns an integer corresponding to the month portion of its type DATE or DATETIME argument.

Syntax
MONTH ( time-expr )

Explanation
MONTH

is a required keyword.

time-expr is a required expression of type DATE or DATETIME.

Notes
1. This function extracts the month from a DATE value, returning an integer m in the range 1 m 12. 2. The time-expr cannot be an INTERVAL argument.

Example
SELECT order_num, MONTH (order_date) FROM orders

INFORMIX-4GL Statement Syntax

7-255

WEEKDAY( )

WEEKDAY( )
Overview
The WEEKDAY( ) function returns an integer that represents the day of the week, when you call it with a type DATE or DATETIME expression.

Syntax
WEEKDAY ( time-expr )

Explanation
WEEKDAY

is a required keyword. is a required expression of type DATE or DATETIME.

time-expr

Notes
1. WEEKDAY returns an integer in the range 0-6. Zero represents Sunday, 1 represents Monday, and so on. 2. The time-expr cannot be a type INTERVAL argument.

Examples
SELECT order_num, WEEKDAY (order_date) FROM orders SELECT * FROM orders WHERE WEEKDAY (paid_date) = WEEKDAY (CURRENT - 31 UNITS DAY)

7-256

INFORMIX-4GL Statement Syntax

YEAR( )

YEAR( )
Overview
The YEAR( ) function returns an integer that represents the year when you call it with a type DATE or DATETIME expression.

Syntax
YEAR ( time-expr )

Explanation
YEAR

is a required keyword.

time-expr is a required expression of type DATE or DATETIME.

Notes
The time-expr cannot be an INTERVAL argument.

Examples
SELECT order_num, YEAR (order_date) FROM orders SELECT order_num, customer_num FROM orders WHERE YEAR(ship_date) < YEAR(TODAY)

The second example species rows in which the ship_date is earlier than the beginning of the current year.

INFORMIX-4GL Statement Syntax

7-257

CURRENT

CURRENT
Overview
The CURRENT function returns a DATETIME value with the date and time of day of the current instant.

Syntax
CURRENT [ rst TO last ]

Explanation
CURRENT

is a required keyword. is a qualier that species the rst eld to be returned. is a required keyword if you specify rst and last. is a qualier that species the last eld to be returned.

rst
TO

last

Notes
1. The value returned is the date and time (from the system clock) when the CURRENT function executes. 2. You can use the CURRENT function in any context in which you can use a DATETIME literal. 3. The rst qualier must specify a eld that is more signicant than or equal to the last qualier. 4. If the function is executed more than once in a statement, identical values may be returned at each point of the call. You cannot rely on CURRENT to provide distinct values each time that it executes. 5. INFORMIX-4GL may not execute the CURRENT function in the physical order in which it appears in a statement. You should not use the function to mark the start, the end, or any specic point in the execution of the 4GL statement. 6. If no rst TO last qualiers are specied, the default qualiers are YEAR TO FRACTION(3).

7-258

INFORMIX-4GL Statement Syntax

CURRENT

7. The following qualiers are valid:

Identier YEAR MONTH DAY HOUR MINUTE SECOND FRACTION (n) Qualied Data A number of years. A number of months. A number of days. A number of hours. A number of minutes. A number of seconds. A decimal fraction of a second with n (up to ve) digits of precision. The default precision is three digits (thousandths of a second).

Example
SELECT prog_title FROM tv_programs WHERE air_date > CURRENT YEAR TO DAY

See also Appendix J, Working with DATETIME and INTERVAL Data.

INFORMIX-4GL Statement Syntax

7-259

EXTEND( )

EXTEND( )
Overview
The EXTEND function adjusts the precision of a DATETIME or DATE value.

Syntax
EXTEND ( value [ , rst TO last ] )

Explanation
EXTEND

is a required keyword. is a DATETIME or DATE type column name, variable, or expression. is an optional qualier that species the rst eld in the result. (See Note 5.) is a required keyword if you include rst and last qualiers. is an optional qualier that species the last eld in the result. (See Note 6.)

value rst
TO

last

Notes
1. The value can also be a DATETIME literal, or a character string in a valid DATETIME format. (It cannot be the string representation of a DATE value.) 2. If no rst TO last qualiers are specied, the default qualiers are YEAR TO FRACTION(3). 3. The rst qualier must specify a eld that is more signicant than or equal to the last qualier. 4. If the value contains elds not specied by the qualiers, the unwanted elds are discarded. 5. If the rst qualier species a eld to the left of (that is, more signicant than) what exists in value, the new elds are lled with values returned by the CURRENT function.

7-260

INFORMIX-4GL Statement Syntax

EXTEND( )

6. If the last qualier species a eld to the right of (that is, less signicant than) what exists in value, the new elds are lled in with constant values. A missing MONTH or DAY is lled in with 1, and the missing elds HOUR to FRACTION are lled in with 0. 7. The following qualiers are valid:
Identier YEAR MONTH DAY HOUR MINUTE SECOND FRACTION (n) Qualied Data A number of years. A number of months. A number of days. A number of hours. A number of minutes. A number of seconds. A decimal fraction of a second with n (up to ve) digits of precision. The default precision is three digits (thousandths of a second).

8. If an INTERVAL value includes a eld that is not present in a DATETIME value, you cannot combine the two values with the addition ( + ) or subtraction ( - ) operators. Similarly, you cannot add or subtract a DATE value and an INTERVAL whose last qualier is smaller than DAY. In these cases, you must use the EXTEND function to return an adjusted DATETIME value on which to perform the arithmetic operation. See also Appendix J, Working with DATETIME and INTERVAL Data.

Examples
In the following example, the EXTEND function returns the MONTH and DAY elds from a column that contains YEAR, MONTH, and DAY data. In this instance the YEAR eld is not returned.
SELECT EXTEND(air_date, MONTH TO DAY) FROM tv_programs

In the next example, assume that air_date is a DATE column, or else a DATETIME column whose last qualier is larger than MINUTE. Then the EXTEND function is required in the following statement, because the INTERVAL operand includes a eld (MINUTE) that is not part of the precision of air_date.
SELECT sponsor, prog_title, air_date FROM tv_programs WHERE air_date >= TODAY AND CURRENT > EXTEND(air_date) - 2880 UNITS MINUTE

INFORMIX-4GL Statement Syntax

7-261

EXTEND( )

Since no qualiers are specied as arguments, the EXTEND function returns a DATETIME value with the default precision YEAR to FRACTION(3). The WHERE clause in this example species the rows in which air_date has a value in a range from the beginning of the current day (TODAY) up to 48 hours (= 2,880 minutes) after the current instant. See also Appendix J, Working with DATETIME and INTERVAL Data. for more information about arithmetic operations on date and time data types.

7-262

INFORMIX-4GL Statement Syntax

Appendix

A
Demonstration Database and Application
The stores Database
The stores database contains a set of tables that describe an imaginary business. You can access the data in stores by the demonstration programs that appear in this book, as well as by application programs that are listed in the documentation of other Informix products. The stores database is not MODE ANSI. This appendix contains ve sections:

The rst section describes the structure of the tables in

the stores database. For each table, the name and the data type of each column are listed. Any indexes on individual columns or on multiple columns are identied and classied as unique or as allowing duplicate values.

The second section presents a graphic map of the tables

in the stores database, showing potential join columns.

The third section discusses the join columns that link

some of the tables in the stores database, and illustrates how you can use these relationships to obtain information from multiple tables.

The fourth section shows the data contained in each

table of the stores database.

Structure of the Tables

The nal section contains the form specications, INFORMIX-4GL source

code modules, and help message source code for the demonstration application. If you have modied or deleted some or all of the data in these tables, you can restore the stores database to its original form by entering i4gldemo (if you have the C Compiler Version), or

r4gldemo (if you have the Rapid Development System). Running this script creates a subdirectory called stores.dbs in your current directory, and places the stores database les there. It also copies all the demonstration programs, forms, and help les into the current directory.

Structure of the Tables

The stores database contains information about a ctitious sporting goods distributor that services stores in the Western United States. This database includes the following tables:

customer orders items stock manufact state

The customer Table

The customer table describes the retail stores that order from the distributor. Information includes each stores name, address, and telephone number, and the name of its representative. The customer table has the following columns: customer_num fname lname company address1 address2 city state zipcode phone serial(101) char(15) char(15) char(20) char(20) char(20) char(15) char(2) char(5) char(18)

The customer_num column is indexed as unique.

A-2 Demonstration Database and Application

Structure of the Tables

The zipcode column is indexed to allow duplicate values.

The orders Table

The orders table contains data about orders placed by customers of the distributor. This information includes the order number, the date when the order was made, the customer number, shipping instructions, the customers purchase order number, the date when the order was shipped, the weight of the order, the shipment charge, and the date when the customer paid for the order. It also tells whether a backlog exists. The columns of the orders table are listed here: order_num order_date customer_num ship_instruct backlog po_num ship_date ship_weight ship_charge paid_date serial(1001) date integer char(40) char(1) char(10) date decimal(8,2) money(6) date

The order_num column is indexed, and must contain unique values. The customer_num column is indexed, but allows duplicates.

The items Table

An order can include one or more items. The items table describes the items in each order. Information in the items table includes the item number, codes for the order, stock, and manufacturer, the quantity, and the total price for the item. The items table has these columns: item_num order_num stock_num manu_code quantity total_price smallint integer smallint char(3) smallint money(8)

The order_num column has an index that allows duplicate values. A multiple-column index for the stock_num and manu_code columns also permits duplicate values.

Demonstration Database and Application

A-3

Structure of the Tables

The stock Table

The distributor carries fteen different types of sporting goods. For example, the distributor offers baseball gloves from three manufacturers, and offers basketballs from one manufacturer. The stock table is a catalog of the items sold by the distributor. For each item in stock, the stock table lists a stock number identifying the type of item, a code identifying the manufacturer, a description of the item, its unit price, the unit by which the item must be ordered, and a description of the unit (for example, a case containing 10 baseballs). These are the names and data types of the columns in the stock table: stock_num manu_code description unit_price unit unit_descr smallint char(3) char(15) money(6) char(4) char(15)

A multiple-column index for both the stock_num and manu_code columns allows only unique values.

The manufact Table

Information about the ve manufacturers whose sporting goods are handled by the distributor is kept in the manufact table. Each row contains a manufacturers identifying code and name. The columns in the manufact table are as follows: manu_code manu_name char(3) char(15)

The manu_code column has an index that requires unique values.

The state Table

The state table contains the names and postal abbreviations of the fty states of the United States. It includes two columns: code sname char(2) char(15)

The code column is indexed as unique.

A-4

Demonstration Database and Application

Map of the stores Database

Map of the stores Database

Figure A-1 displays the column names of the tables in the stores database, and indicates which columns in different tables contain the same information.
items orders order_num customer customer_num fname lname company address1 address2 state code sname Figure A-1 city state zipcode phone Tables in the stores Database order_date customer_num ship_instruct backlog po_num ship_date ship_weight ship_charge paid_date item_num order_num stock_num manu_code quantity total_price stock stock_num manu_code description unit_price unit unit_descr manufact manu_code manu_name

Join Columns That Link the Database

The tables of the stores database are linked together by join columns, which are identied in this section. You can use them to retrieve and display information from several tables at once, as if it had been stored in a single table. Figures A-2 through A-6 show the relationships among tables, and how information stored in one table supplements information in others.

Join Columns in the customer and orders Tables

The customer_num column joins the customer table and the orders table, as shown in Figure A-2.

Demonstration Database and Application

A-5

Join Columns That Link the Database

customer_num 101 102 103 104 order_num 1001 1002 1003 1004 Figure A-2

fname Ludwig Carole Philip Anthony order_date 01/20/1989 06/01/1989 10/12/1989 04/12/1989

lname Pauli Sadler Currie Higgins customer_num 104 101 104 106

customer table (detail)

orders table (detail)

Tables Joined by the customer_num Column

The customer table contains a customer_num column that holds a number identifying a customer, along with columns for the customers name, company, address, and telephone number. For example, the row with information about Anthony Higgins contains the number 104 in the customer_num column. The orders table also contains a customer_num column that stores the number of the customer who placed a particular order. According to Figure A-2, customer 104 (Anthony Higgins) has placed two orders, since his customer number appears in two rows of the orders table. The join relationship lets you select information from both tables. This means that you can retrieve Anthony Higginss name and address and information about his orders at the same time.

Join Columns in the orders and items Tables

The orders and items tables are linked by an order_num column that contains an identication number for each order. If an order includes several items, the same order number appears in several rows of the items table. Figure A-3 shows this relationship.

A-6

Demonstration Database and Application

Join Columns That Link the Database

order_num 1001 1002 1003 1004 item_num 1 1 2 1 2 3 Figure A-3

order_date 01/20/1989 06/01/1989 10/12/1989 04/12/1989 order_num 1001 1002 1002 1003 1003 1003

customer_num 104 101 104 106 manu_code HRO HSK HSK ANZ ANZ ANZ

orders table (detail)

stock_num 1 4 3 9 8 5

items table (detail)

Tables Joined by the order_num Column

Join Columns in the items and stock Tables

The items table and the stock table are joined by two columns: the stock_num column stores a stock number for an item, and the manu_code column stores a code to identify the manufacturer. You need both the stock number and the manufacturer code to uniquely identify an item. For example, the item with the stock number 1 and the manufacturer code HRO is a Hero baseball glove, while the item with the stock number 1 and and the manufacturer code HSK is a Husky baseball glove.

Demonstration Database and Application

A-7

Join Columns That Link the Database

item_num 1 1 2 1 2 3 1 stock_num 1 1 1 Figure A-4

order_num 1001 1002 1002 1003 1003 1003 1004 manu_code HRO HSK SMT

stock_num 1 4 3 9 8 5 1 description baseball glove baseball glove baseball glove

manu_code HRO HSK HSK ANZ ANZ ANZ HRO

items table (detail)

stock table (detail)

Tables Joined by Two Columns

The same stock number and manufacturer code can appear in more than one row of the items table, if the same item belongs to separate orders. This is illustrated above in Figure A-4.

Join Columns in the stock and manufact Tables

The stock table and the manufact table are joined by the manu_code column. The same manufacturer code can appear in more than one row of the stock table if the manufacturer produces more than one piece of equipment. This relationship is illustrated in Figure A-5.
stock_num 1 1 1 2 manu_code NRG HSK HRO Figure A-5 manu_code HRO HSK SMT HRO manu_name Norge Husky Hero description baseball glove baseball glove baseball glove baseball stock table (detail)

manufact table (detail)

Tables Joined by the manu_code Column

A-8

Demonstration Database and Application

Data in the stores Database

Join Columns in the state and customer Tables

The state table and the customer table are joined by a column that contains the state code. This column is called code in the state table and state in the customer table. If several customers live in the same state, the same state code will appear in several rows of the customer table, as shown in Figure A6.
customer_num 101 102 103 code AK AL AR AZ CA Figure A-6 fname Ludwig Carole Philip sname Alaska Alabama Arkansas Arizona California lname Pauli Sadler Currie ... ... ... ... state CA CA CA customer table (detail)

state table (detail)

Tables Joined by the State-Code Column

Joining lets you rearrange your view of a database whenever you want. It provides exibility that lets you create new relationships between tables without redesigning the database. You can easily expand the scope of a database by adding new tables that join the existing tables. As you read through this manual, you will see programs that set up the join relationships across tables of the stores database. Refer to these gures whenever you need to review these relationships.

Data in the stores Database

The tables that follow display the data in the stores database.

Demonstration Database and Application

A-9

A-10

customer Table
fname
Ludwig Carole Philip Anthony Raymond George Charles Donald Jane Roy Frances Margaret Lana Frank Alfred Jean Arnold Dick Baxter Blue Ribbon Sports Sipes Kids Korner Parmelee Olympic City Grant Gold Medal Sports Albertson Sporting Place Beatty Sportstown 654 Oak Grove 947 Waverly Place 776 Gary Avenue 1104 Spinosa Drive 850 Lytton Court 5427 College Lawson Runners & Others 234 Wyandotte Way Keyes Sports Center 3199 Sterling Court Jaeger AA Athletics 520 Topaz Way Miller Sport Stuff Mayfair Mart Quinn Quinns Sports 587 Alvarado Ream Athletic Supplies 41 Jordan Avenue Watson Watson & Son 1143 Carver Place Vector Los Altos Sports 1899 La Loma Drive Higgins Play Ball! East Shopping Cntr. 422 Bay Road Los Altos Mountain View Palo Alto Redwood City 7345 Ross Blvd. Sunnyvale Redwood City Sunnyvale Los Altos Menlo Park Redwood City Menlo Park Mountain View Redwood City Oakland Currie Phils Sports 654 Poplar P. O. Box 3498 Palo Alto Redwood City Sadler Sports Spot 785 Geary St San Francisco Pauli All Sports Supplies 213 Erstwild Court Sunnyvale CA CA CA CA CA CA CA CA CA CA CA CA CA CA CA CA CA CA

customer_num

lname

company

address1

address2

city

state

zip code
94086 94117 94303 94026 94022 94063 94304 94063 94086 94062 94085 94022 94025 94062 94025 94040 94063 94609

phone
408-789-8075 415-822-1289 415-328-4543 415-368-1100 415-776-3249 415-389-8789 415-356-9876 415-544-8729 408-723-8789 415-743-3611 408-277-7245 415-887-7235 415-356-9982 415-886-6677 415-356-1123 415-534-8822 415-245-4578 415-655-0011

101

102

Demonstration Database and Application

103

104

105

Data in the stores Database

106

107

108

109

110

111

112

113

114

115

116

117

118

Data in the stores Database

items Table
item_num 1 1 2 1 2 3 1 2 3 4 1 2 3 4 1 2 3 4 5 1 2 3 4 5 1 2 1 1 2 1 1 2 1 2 3 4 1 2 1 order_num 1001 1002 1002 1003 1003 1003 1004 1004 1004 1004 1005 1005 1005 1005 1006 1006 1006 1006 1006 1007 1007 1007 1007 1007 1008 1008 1009 1010 1010 1011 1012 1012 1013 1013 1013 1013 1014 1014 1015 stock_num 1 4 3 9 8 5 1 2 3 1 5 5 6 6 5 5 5 6 6 1 2 3 4 7 8 9 1 6 6 5 8 9 5 6 6 9 4 4 1 manu_code HRO HSK HSK ANZ ANZ ANZ HRO HRO HSK HSK NRG ANZ SMT ANZ SMT NRG ANZ SMT ANZ HRO HRO HSK HRO HRO ANZ ANZ SMT SMT ANZ ANZ ANZ ANZ ANZ SMT ANZ ANZ HSK HRO SMT quantity 1 1 1 1 1 5 1 1 1 1 10 10 1 1 5 5 5 1 1 1 1 1 1 1 1 5 1 1 1 5 1 10 1 1 1 2 1 1 1 total_price 250.0 960.0 240.0 20.0 840.0 99.0 960.0 126.0 240.0 800.0 280.0 198.0 36.0 48.0 125.0 190.0 99.0 36.0 48.0 250.0 126.0 240.0 480.0 600.0 840.0 100.0 450.0 36.0 48.0 99.0 840.0 200.0 19.8 36.0 48.0 40.0 960.0 480.0 450.0

Demonstration Database and Application

A-11

A-12

orders Table
ship_instruct
ups po on box; deliver back door only via ups ring bell twice call before delivering after 10 am n closed Monday door next to supersaver deliver 776 Gary if no answer ups n via ups closed Mon n n ring bell, kick door loudly n n n n 4745 429Q B77897 278701 B77930 8052 MA003 y LZ230 278693 y Q13557 04/23/89 12/06/89 03/04/89 06/08/89 04/13/89 06/09/89 09/18/89 05/10/89 08/01/89 n 2865 y 8006 04/30/89 12/19/89 n B77890 10/13/89 n 9270 06/06/89 n B77836 02/01/89 20.40 50.60 35.60 95.80 80.80 70.80 125.90 45.60 20.40 40.60 10.40 70.80 60.80 40.60 20.60

order_num order_date customer_num

01/20/89 06/01/89 10/12/89 04/12/89 12/04/89 09/19/89 03/25/89 11/17/89 02/14/89 05/29/89 03/23/89 06/05/89 09/01/89 05/01/89 07/10/89 110 106 104 117 104 115 111 110 117 112 116 106 104 101 104

backlog

po_num

ship_date

ship_weight

ship_charge
10.00 15.30 10.80 19.20 16.20 14.20 25.20 13.80 10.00 12.30 5.00 14.20 12.20 12.30 6.30

paid_ date
03/22/89 07/03/89 11/04/89 12/30/89

1001

1002

1003

Demonstration Database and Application

1004

1005

Data in the stores Database

1006

1007

1008

12/21/89 04/21/89 07/22/89 06/01/89 10/10/89 07/18/89 08/31/89

1009

1010

1011

1012

1013

1014

1015

Data in the stores Database

stock Table
stock_num 1 1 1 2 3 4 4 5 5 5 6 6 7 8 9 manu_code HRO HSK SMT HRO HSK HSK HRO NRG SMT ANZ SMT ANZ HRO ANZ ANZ description baseball gloves baseball gloves baseball gloves baseball baseball bat football football tennis racquet tennis racquet tennis racquet tennis ball tennis ball basketball volleyball volleyball net unit_price 250.00 800.00 450.00 126.00 240.00 960.00 480.00 28.00 25.00 19.80 36.00 48.00 600.00 840.00 20.00 unit case case case case case case case each each each case case case case each unit_descr 10 gloves/case 10 gloves/case 10 gloves/case 24/case 12/case 24/case 24/case each each each 24 cans/case 24 cans/case 24/case 24/case each

manufact Table
manu_code ANZ HSK HRO NRG SMT manu_name Anza Husky Hero Norge Smith

Demonstration Database and Application

A-13

Data in the stores Database

state Table
code AK AL AR AZ CA CO CT DE FL GA HI IA ID IL IN KS KY LA MA MD ME MI MN MO MS sname Alaska Alabama Arkansas Arizona California Colorado Connecticut Delaware Florida Georgia Hawaii Iowa Idaho Illinois Indiana Kansas Kentucky Louisiana Massachusetts Maryland Maine Michigan Minnesota Missouri Mississippi code MT NB NC ND NH NJ NM NV NY OH OK OR PA RI SC SD TN TX UT VA VT WA WI WV WY sname Montana Nebraska North Carolina North Dakota New Hampshire New Jersey New Mexico Nevada New York Ohio Oklahoma Oregon Pennsylvania Rhode Island South Carolina South Dakota Tennessee Texas Utah Virginia Vermont Washington Wisconsin West Virginia Wyoming

A-14

Demonstration Database and Application

The Demonstration Application

The Demonstration Application

The following pages contain the form specications, INFORMIX-4GL source code modules, and help message source le for the demo4.4ge demonstration application. The application is not complete, and some of the functions called by the menus are merely dead ends.
File Name custform.per orderform.per state_list.per stock_sel.per d4_globals.4gl d4_main.4gl d4_cust.4gl d4_orders.4gl d4_stock.4gl d4_report.4gl d4_demo.4gl helpdemo.src Description Form for displaying customer information Form for entering an order Form for displaying a list of states Form for displaying a list of stock items Module containing global denitions Module containing MAIN routine Module handling the Customer option Module handling the Orders option Module handling the Stock option Module handling the Report option Module handling hidden sample source code option Source le for help messages

custform.per
DATABASE stores SCREEN {

Customer Form Number Owner Name Company Address City Telephone } TABLES customer ATTRIBUTES f000 = customer.customer_num, NOENTRY; f001 = customer.fname; f002 = customer.lname; f003 = customer.company; f004 = customer.address1; f005 = customer.address2; f006 = customer.city; a0 = customer.state, UPSHIFT; f007 = customer.zipcode; f008 = customer.phone, PICTURE = "###-###-#### XXXXX"; :[f000 :[f001 :[f003 :[f004 [f005 :[f006 :[f008 ] ][f002 ] ] ] ] ] State:[a0] Zipcode:[f007 ] ]

Demonstration Database and Application

A-15

The Demonstration Application

orderform.per
DATABASE stores SCREEN { -----------------------------------------------------------------------------ORDER FORM -----------------------------------------------------------------------------Customer Number:[f000 ] Contact Name:[f001 ][f002 ] Company Name:[f003 ] Address:[f004 ][f005 ] City:[f006 ] State:[a0] Zip Code:[f007 ] Telephone:[f008 ] -----------------------------------------------------------------------------Order No:[f009 ] Order Date:[f010 ] PO Number:[f011 ] Shipping Instructions:[f012 ] -----------------------------------------------------------------------------Item No. Stock No. Code Description Quantity Price Total [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] [f013 ] [f014 ] [a1 ] [f015 ] [f016 ] [f017 ] [f018 ] Running Total including Tax and Shipping Charges:[f019 ] ============================================================================== } TABLES customer orders items stock ATTRIBUTES f000 = customer.customer_num; f001 = customer.fname; f002 = customer.lname; f003 = customer.company; f004 = customer.address1; f005 = customer.address2; f006 = customer.city; a0 = customer.state, UPSHIFT; f007 = customer.zipcode; f008 = customer.phone, PICTURE = "###-###-#### XXXXX"; f009 f010 f011 f012 f013 f014 a1 = f015 f016 f017 f018 f019 = = = = orders.order_num; orders.order_date, DEFAULT = TODAY; orders.po_num; orders.ship_instruct;

= items.item_num, NOENTRY; = items.stock_num; items.manu_code, UPSHIFT; = stock.description, NOENTRY; = items.quantity; = stock.unit_price, NOENTRY; = items.total_price, NOENTRY; = formonly.t_price TYPE MONEY;

INSTRUCTIONS SCREEN RECORD s_items[4](items.item_num, items.stock_num, items.manu_code, stock.description, items.quantity, stock.unit_price, items.total_price)

A-16

Demonstration Database and Application

The Demonstration Application

state_list.per
DATABASE stores SCREEN { State Selection [a0] [a0] [a0] [a0] [a0] [a0] [a0] } [f000 [f000 [f000 [f000 [f000 [f000 [f000 ] ] ] ] ] ] ]

TABLES state ATTRIBUTES a0 = state.code; f000 = state.sname; INSTRUCTIONS DELIMITERS " " SCREEN RECORD s_state[7](state.*)

stock_sel.per
DATABASE stores SCREEN { [f018][f019][f020 [f018][f019][f020 [f018][f019][f020 } TABLES stock ATTRIBUTES f018 = FORMONLY.stock_num; f019 = FORMONLY.manu_code; f020 = FORMONLY.manu_name; f021 = FORMONLY.description; f022 = FORMONLY.unit_price; f023 = FORMONLY.unit_descr; INSTRUCTIONS DELIMITERS " " SCREEN RECORD s_stock[3] (FORMONLY.stock_num THRU FORMONLY.unit_descr)

][f021 ][f021 ][f021

][f022 ][f022 ][f022

][f023 ][f023 ][f023

] ] ]

Demonstration Database and Application

A-17

The Demonstration Application

d4_globals.4gl
DATABASE stores GLOBALS DEFINE p_customer RECORD LIKE customer.*, p_orders RECORD order_num LIKE orders.order_num, order_date LIKE orders.order_date, po_num LIKE orders.po_num, ship_instruct LIKE orders.ship_instruct END RECORD, p_items ARRAY[10] OF RECORD item_num LIKE items.item_num, stock_num LIKE items.stock_num, manu_code LIKE items.manu_code, description LIKE stock.description, quantity LIKE items.quantity, unit_price LIKE stock.unit_price, total_price LIKE items.total_price END RECORD, p_stock ARRAY[30] OF RECORD stock_num LIKE stock.stock_num, manu_code LIKE manufact.manu_code, manu_name LIKE manufact.manu_name, description LIKE stock.description, unit_price LIKE stock.unit_price, unit_descr LIKE stock.unit_descr END RECORD, p_state ARRAY[50] OF RECORD LIKE state.*, state_cnt, stock_cnt INTEGER, print_option CHAR(1) END GLOBALS

A-18

Demonstration Database and Application

The Demonstration Application

d4_main.4gl
GLOBALS "d4_globals.4gl"

MAIN DEFER INTERRUPT OPTIONS HELP FILE "helpdemo" LET print_option = "s" CALL get_states() CALL get_stocks() CALL ring_menu() MENU "MAIN" COMMAND "Customer" "Enter and maintain customer data" HELP 101 CALL customer() CALL ring_menu() COMMAND "Orders" "Enter and maintain orders" HELP 102 CALL orders() CALL ring_menu() COMMAND "Stock" "Enter and maintain stock list" HELP 103 CALL stock() CALL ring_menu() COMMAND "Reports" "Print reports and mailing labels" HELP 104 CALL reports() CALL ring_menu() COMMAND key("!") CALL bang() CALL ring_menu() NEXT OPTION "Customer" COMMAND key("X") CALL demo() CALL ring_menu() NEXT OPTION "Customer" COMMAND "Exit" "Exit program and return to operating system" HELP 105 CLEAR SCREEN EXIT PROGRAM END MENU END MAIN

FUNCTION bang() DEFINE cmd CHAR(80), x CHAR(1) CALL clear_menu() LET x = "!" WHILE x = "!" PROMPT "!" FOR cmd RUN cmd PROMPT "Type RETURN to continue." FOR CHAR x END WHILE END FUNCTION

FUNCTION mess(str, mrow) DEFINE str CHAR(80),

Demonstration Database and Application

A-19

The Demonstration Application

mrow SMALLINT DISPLAY " ", str CLIPPED AT mrow,1 SLEEP 3 DISPLAY "" AT mrow,1 END FUNCTION

FUNCTION ring_menu() DISPLAY "----------------------------------------- ", "Type Control-W for MENU HELP -------" AT 4,2 ATTRIBUTE(MAGENTA) END FUNCTION

FUNCTION clear_menu() DISPLAY "" AT 1,1 DISPLAY "" AT 2,1 END FUNCTION

FUNCTION get_states() DECLARE c_state CURSOR FOR SELECT * FROM state ORDER BY sname LET state_cnt = 1 FOREACH c_state INTO p_state[state_cnt].* LET state_cnt = state_cnt + 1 IF state_cnt > 50 THEN EXIT FOREACH END IF END FOREACH LET state_cnt = state_cnt - 1 END FUNCTION

FUNCTION get_stocks() DECLARE stock_list CURSOR FOR SELECT stock_num, manufact.manu_code, manu_name, description, unit_price, unit_descr FROM stock, manufact WHERE stock.manu_code = manufact.manu_code ORDER BY stock_num LET stock_cnt = 1 FOREACH stock_list INTO p_stock[stock_cnt].* LET stock_cnt = stock_cnt + 1 IF stock_cnt > 30 THEN EXIT FOREACH END IF END FOREACH LET stock_cnt = stock_cnt - 1 END FUNCTION

A-20

Demonstration Database and Application

The Demonstration Application

d4_cust.4gl
GLOBALS "d4_globals.4gl" FUNCTION customer() OPTIONS FORM LINE 7 OPEN FORM customer FROM "custform" DISPLAY FORM customer ATTRIBUTE(MAGENTA) CALL ring_menu() CALL fgl_drawbox(3,30,3,43) CALL fgl_drawbox(3,61,8,7) CALL fgl_drawbox(11,61,8,7) LET p_customer.customer_num = NULL MENU "CUSTOMER" COMMAND "One-add" "Add a new customer to the database" HELP 201 CALL add_customer(FALSE) COMMAND "Many-add" "Add several new customer to database" HELP 202 CALL add_customer(TRUE) COMMAND "Find-cust" "Look up specific customer" HELP 203 CALL query_customer(23) IF p_customer.customer_num IS NOT NULL THEN NEXT OPTION "Update-cust" END IF COMMAND "Update-cust" "Modify current customer information" HELP 204 CALL update_customer() NEXT OPTION "Find-cust" COMMAND "Delete-cust" "Remove a customer from database" HELP 205 CALL delete_customer() NEXT OPTION "Find-cust" COMMAND "Exit" "Return to MAIN Menu" HELP 206 CLEAR SCREEN EXIT MENU END MENU OPTIONS FORM LINE 3 END FUNCTION

FUNCTION add_customer(repeat) DEFINE repeat INTEGER CALL clear_menu() MESSAGE "Press F1 or CTRL-F for field help; ", "F2 or CTRL-Z to return to menu" IF repeat THEN WHILE input_cust() ERROR "Customer data entered" ATTRIBUTE (GREEN) END WHILE CALL mess("Multiple insert completed - current screen values ignored", 23) ELSE IF input_cust() THEN ERROR "Customer data entered" ATTRIBUTE (GREEN) ELSE CLEAR FORM LET p_customer.customer_num = NULL ERROR "Customer addition aborted" ATTRIBUTE (RED, REVERSE) END IF END IF END FUNCTION FUNCTION input_cust()

Demonstration Database and Application

A-21

The Demonstration Application

DISPLAY "Press ESC to enter new customer data" AT 1,1 INPUT BY NAME p_customer.* AFTER FIELD state CALL statehelp() DISPLAY "Press ESC to enter new customer data", "" AT 1,1 ON KEY (F1, CONTROL-F) CALL customer_help() ON KEY (F2, CONTROL-Z) LET int_flag = TRUE EXIT INPUT END INPUT IF int_flag THEN LET int_flag = FALSE RETURN(FALSE) END IF LET p_customer.customer_num = 0 INSERT INTO customer VALUES (p_customer.*) LET p_customer.customer_num = SQLCA.SQLERRD[2] DISPLAY BY NAME p_customer.customer_num ATTRIBUTE(MAGENTA) RETURN(TRUE) END FUNCTION

FUNCTION query_customer(mrow) DEFINE where_part CHAR(200), query_text CHAR(250), answer CHAR(1), mrow, chosen, exist SMALLINT CLEAR FORM CALL clear_menu() MESSAGE "Enter criteria for selection" CONSTRUCT where_part ON customer.* FROM customer.* MESSAGE "" IF int_flag THEN LET int_flag = FALSE CLEAR FORM ERROR "Customer query aborted" ATTRIBUTE(RED, REVERSE) LET p_customer.customer_num = NULL RETURN (p_customer.customer_num) END IF LET query_text = "select * from customer where ", where_part CLIPPED, " order by lname" PREPARE statement_1 FROM query_text DECLARE customer_set SCROLL CURSOR FOR statement_1

A-22

Demonstration Database and Application

The Demonstration Application

OPEN customer_set FETCH FIRST customer_set INTO p_customer.* IF status = NOTFOUND THEN LET exist = FALSE ELSE LET exist = TRUE DISPLAY BY NAME p_customer.* MENU "BROWSE" COMMAND "Next" "View the next customer in the list" FETCH NEXT customer_set INTO p_customer.* IF status = NOTFOUND THEN ERROR "No more customers in this direction" ATTRIBUTE(RED, REVERSE) FETCH LAST customer_set INTO p_customer.* END IF DISPLAY BY NAME p_customer.* ATTRIBUTE(CYAN) COMMAND "Previous" "View the previous customer in the list" FETCH PREVIOUS customer_set INTO p_customer.* IF status = NOTFOUND THEN ERROR "No more customers in this direction" ATTRIBUTE(RED, REVERSE) FETCH FIRST customer_set INTO p_customer.* END IF DISPLAY BY NAME p_customer.* ATTRIBUTE(CYAN) COMMAND "First" "View the first customer in the list" FETCH FIRST customer_set INTO p_customer.* DISPLAY BY NAME p_customer.* ATTRIBUTE(CYAN) COMMAND "Last" "View the last customer in the list" FETCH LAST customer_set INTO p_customer.* DISPLAY BY NAME p_customer.* ATTRIBUTE(CYAN) COMMAND "Select" "Exit BROWSE selecting the current customer" LET chosen = TRUE EXIT MENU COMMAND "Quit" "Quit BROWSE without selecting a customer" LET chosen = FALSE EXIT MENU END MENU END IF CLOSE customer_set IF NOT exist THEN CLEAR FORM CALL mess("No customer satisfies query", mrow) LET p_customer.customer_num = NULL RETURN (FALSE) END IF IF NOT chosen THEN CLEAR FORM LET p_customer.customer_num = NULL CALL mess("No selection made", mrow) RETURN (FALSE) END IF RETURN (TRUE) END FUNCTION

Demonstration Database and Application

A-23

The Demonstration Application

FUNCTION update_customer() CALL clear_menu() IF p_customer.customer_num IS NULL THEN CALL mess("No customer has been selected; use the Find-cust option",23) RETURN END IF MESSAGE "Press F1 or CTRL-F for field-level help" DISPLAY "Press ESC to update customer data; DEL to abort" AT 1,1 INPUT BY NAME p_customer.* WITHOUT DEFAULTS AFTER FIELD state CALL statehelp() DISPLAY "Press ESC to update customer data; DEL to abort", "" AT 1,1 ON KEY (F1, CONTROL-F) CALL customer_help() END INPUT IF NOT int_flag THEN UPDATE customer SET customer.* = p_customer.* WHERE customer_num = p_customer.customer_num CALL mess("Customer data modified", 23) ELSE LET int_flag = FALSE SELECT * INTO p_customer.* FROM customer WHERE customer_num = p_customer.customer_num DISPLAY BY NAME p_customer.* ERROR "Customer update aborted" ATTRIBUTE (RED, REVERSE) END IF END FUNCTION

FUNCTION delete_customer() DEFINE answer CHAR(1), num_orders INTEGER CALL clear_menu() IF p_customer.customer_num IS NULL THEN ERROR "No customer has been selected; use the Find-customer option" ATTRIBUTE (RED, REVERSE) RETURN END IF SELECT COUNT(*) INTO num_orders FROM orders WHERE customer_num = p_customer.customer_num IF num_orders THEN ERROR "This customer has active orders and can not be removed" ATTRIBUTE (RED, REVERSE) RETURN END IF PROMPT " Are you sure you want to delete this customer row? " FOR CHAR answer IF answer MATCHES "[yY]" THEN DELETE FROM customer WHERE customer_num = p_customer.customer_num CLEAR FORM CALL mess("Customer entry deleted", 23) LET p_customer.customer_num = NULL ELSE ERROR "Deletion aborted" ATTRIBUTE (RED, REVERSE) END IF END FUNCTION

A-24

Demonstration Database and Application

The Demonstration Application

FUNCTION customer_help() CASE WHEN infield(customer_num) CALL showhelp(1001) WHEN infield(fname) CALL showhelp(1002) WHEN infield(lname) CALL showhelp(1003) WHEN infield(company) CALL showhelp(1004) WHEN infield(address1) CALL showhelp(1005) WHEN infield(address2) CALL showhelp(1006) WHEN infield(city) CALL showhelp(1007) WHEN infield(state) CALL showhelp(1008) WHEN infield(zipcode) CALL showhelp(1009) WHEN infield(phone) CALL showhelp(1010) END CASE END FUNCTION

FUNCTION statehelp() DEFINE idx INTEGER SELECT COUNT(*) INTO idx FROM state WHERE code = p_customer.state IF idx = 1 THEN RETURN END IF DISPLAY "Move cursor using F3, F4, and arrow keys; press ESC to select state" AT 1,1 OPEN WINDOW w_state AT 8,37 WITH FORM "state_list" ATTRIBUTE (BORDER, RED, FORM LINE 2) CALL set_count(state_cnt) DISPLAY ARRAY p_state TO s_state.* LET idx = arr_curr() CLOSE WINDOW w_state LET p_customer.state = p_state[idx].code DISPLAY BY NAME p_customer.state ATTRIBUTE (MAGENTA) RETURN END FUNCTION

Demonstration Database and Application

A-25

The Demonstration Application

d4_orders.4gl
GLOBALS "d4_globals.4gl" FUNCTION orders() OPEN FORM order_form FROM "orderform" DISPLAY FORM order_form ATTRIBUTE(MAGENTA) MENU "ORDERS" COMMAND "Add-order" "Enter new order to database and print invoice" HELP 301 CALL add_order() COMMAND "Update-order" "Enter shipping or payment data" HELP 302 CALL update_order() COMMAND "Find-order" "Look up and display orders" HELP 303 CALL get_order() COMMAND "Delete-order" "Remove an order from the database" HELP 304 CALL delete_order() COMMAND "Exit" "Return to MAIN Menu" HELP 305 CLEAR SCREEN EXIT MENU END MENU END FUNCTION FUNCTION add_order() DEFINE pa_curr, s_curr, num_stocks INTEGER, file_name CHAR(20), query_stat INTEGER CALL clear_menu() LET query_stat = query_customer(2) IF query_stat IS NULL THEN RETURN END IF IF NOT query_stat THEN OPEN WINDOW cust_w AT 3,5 WITH 19 ROWS, 72 COLUMNS ATTRIBUTE(BORDER, YELLOW) OPEN FORM o_cust FROM "custform" DISPLAY FORM o_cust ATTRIBUTE(MAGENTA) CALL fgl_drawbox(3,61,4,7) CALL fgl_drawbox(11,61,4,7) CALL add_customer(FALSE) CLOSE FORM o_cust CLOSE WINDOW cust_w IF p_customer.customer_num IS NULL THEN RETURN ELSE DISPLAY by name p_customer.* END IF END IF MESSAGE "Enter the order date, PO number and shipping instructions." INPUT BY NAME p_orders.order_date, p_orders.po_num, p_orders.ship_instruct IF int_flag THEN LET int_flag = FALSE CLEAR FORM ERROR "Order input aborted" ATTRIBUTE (RED, REVERSE) RETURN END IF INPUT ARRAY p_items FROM s_items.* HELP 311

A-26

Demonstration Database and Application

The Demonstration Application

BEFORE FIELD stock_num MESSAGE "Press ESC to write order" DISPLAY "Enter a stock number or press CTRL-B to scan stock list" AT 1,1 BEFORE FIELD manu_code MESSAGE "Enter the code for a manufacturer" BEFORE FIELD quantity DISPLAY "" AT 1,1 MESSAGE "Enter the item quantity" ON KEY (CONTROL-B) IF INFIELD(stock_num) OR INFIELD(manu_code) THEN LET pa_curr = arr_curr() LET s_curr = scr_line() CALL get_stock() RETURNING p_items[pa_curr].stock_num, p_items[pa_curr].manu_code, p_items[pa_curr].description, p_items[pa_curr].unit_price DISPLAY p_items[pa_curr].stock_num TO s_items[s_curr].stock_num DISPLAY p_items[pa_curr].manu_code TO s_items[s_curr].manu_code DISPLAY p_items[pa_curr].description TO s_items[s_curr].description DISPLAY p_items[pa_curr].unit_price TO s_items[s_curr].unit_price NEXT FIELD quantity END IF AFTER FIELD stock_num, manu_code 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 THEN CALL get_item() END IF AFTER FIELD quantity MESSAGE "" LET pa_curr = arr_curr() IF p_items[pa_curr].unit_price IS NOT NULL AND p_items[pa_curr].quantity IS NOT NULL THEN CALL item_total() ELSE ERROR "A valid stock code, manufacturer, and quantity must all be entered" ATTRIBUTE (RED, REVERSE) NEXT FIELD stock_num END IF AFTER INSERT, DELETE CALL renum_items() CALL order_total() AFTER ROW CALL order_total() END INPUT IF int_flag THEN LET int_flag = FALSE CLEAR FORM ERROR "Order input aborted" ATTRIBUTE (RED, REVERSE) RETURN END IF

Demonstration Database and Application

A-27

The Demonstration Application

WHENEVER ERROR CONTINUE BEGIN WORK INSERT INTO orders (order_num, order_date, customer_num, ship_instruct, po_num) VALUES (0, p_orders.order_date, p_customer.customer_num, p_orders.ship_instruct, p_orders.po_num) IF status < 0 THEN ROLLBACK WORK ERROR "Unable to complete update of orders table" ATTRIBUTE(RED, REVERSE, BLINK) RETURN END IF LET p_orders.order_num = SQLCA.SQLERRD[2] DISPLAY BY NAME p_orders.order_num IF NOT insert_items() THEN ROLLBACK WORK ERROR "Unable to insert items" ATTRIBUTE(RED, REVERSE, BLINK) RETURN END IF COMMIT WORK WHENEVER ERROR STOP CALL mess("Order added", 23) LET file_name = "inv", p_orders.order_num USING "<<<<&",".out" CALL invoice(file_name) CLEAR FORM END FUNCTION

FUNCTION update_order() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION delete_order() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION order_total() DEFINE order_total MONEY(8), i INTEGER LET order_total = 0.00 FOR i = 1 TO ARR_COUNT() IF p_items[i].total_price IS NOT NULL THEN LET order_total = order_total + p_items[i].total_price END IF END FOR LET order_total = 1.1 * order_total DISPLAY order_total TO t_price ATTRIBUTE(GREEN) END FUNCTION

A-28

Demonstration Database and Application

The Demonstration Application

FUNCTION item_total() DEFINE pa_curr, sc_curr INTEGER LET pa_curr = arr_curr() LET sc_curr = scr_line() LET p_items[pa_curr].total_price = p_items[pa_curr].quantity * p_items[pa_curr].unit_price DISPLAY p_items[pa_curr].total_price TO s_items[sc_curr].total_price END FUNCTION

FUNCTION renum_items() DEFINE pa_curr, pa_total, sc_curr, sc_total, k INTEGER pa_curr = arr_curr() pa_total = arr_count() sc_curr = scr_line() sc_total = 4 k = pa_curr TO pa_total LET p_items[k].item_num = k IF sc_curr <= sc_total THEN DISPLAY k TO s_items[sc_curr].item_num LET sc_curr = sc_curr + 1 END IF END FOR END FUNCTION LET LET LET LET FOR

FUNCTION insert_items() DEFINE idx INTEGER FOR idx = 1 TO arr_count() IF p_items[idx].quantity != 0 THEN INSERT INTO items VALUES (p_items[idx].item_num, p_orders.order_num, p_items[idx].stock_num, p_items[idx].manu_code, p_items[idx].quantity, p_items[idx].total_price) IF status < 0 THEN RETURN (FALSE) END IF END IF END FOR RETURN (TRUE) END FUNCTION

FUNCTION get_stock() DEFINE idx integer OPEN WINDOW stock_w AT 7, 3 WITH FORM "stock_sel" ATTRIBUTE(BORDER, YELLOW) CALL set_count(stock_cnt) DISPLAY "Use cursor using F3, F4, and arrow keys; press ESC to select a stock item" AT 1,1 DISPLAY ARRAY p_stock TO s_stock.* LET idx = arr_curr() CLOSE WINDOW stock_w RETURN p_stock[idx].stock_num, p_stock[idx].manu_code, p_stock[idx].description, p_stock[idx].unit_price END FUNCTION

Demonstration Database and Application

A-29

The Demonstration Application

FUNCTION get_order() DEFINE idx, exist, chosen INTEGER, answer CHAR(1) CALL clear_menu() CLEAR FORM IF NOT query_customer(2) THEN RETURN END IF DECLARE order_list CURSOR FOR SELECT order_num, order_date, po_num, ship_instruct FROM orders WHERE customer_num = p_customer.customer_num LET exist = FALSE LET chosen = FALSE FOREACH order_list INTO p_orders.* LET exist = TRUE CLEAR orders.* FOR idx = 1 TO 4 CLEAR s_items[idx].* END FOR DISPLAY p_orders.* TO orders.* DECLARE item_list CURSOR FOR SELECT item_num, items.stock_num, items.manu_code, description, quantity, unit_price, total_price FROM items, stock WHERE order_num = p_orders.order_num AND items.stock_num = stock.stock_num AND items.manu_code = stock.manu_code ORDER BY item_num LET idx = 1 FOREACH item_list INTO p_items[idx].* LET idx = idx + 1 IF idx > 10 THEN ERROR "More than 10 items; only 10 items displayed" ATTRIBUTE (RED, REVERSE) EXIT FOREACH END IF END FOREACH CALL set_count(idx - 1) CALL order_total() MESSAGE "Press ESC when you finish viewing the items" DISPLAY ARRAY p_items TO s_items.* ATTRIBUTE(CYAN) MESSAGE "" IF int_flag THEN LET int_flag = FALSE EXIT FOREACH END IF PROMPT " Enter y to select this order ", "or RETURN to view next order: " FOR CHAR answer IF answer MATCHES "[yY]" THEN LET chosen = TRUE EXIT FOREACH END IF END FOREACH IF NOT exist THEN ERROR "No orders found for this customer" ATTRIBUTE (RED) ELSE IF NOT chosen THEN CLEAR FORM ERROR "No order selected for this customer" ATTRIBUTE (RED) END IF

A-30

Demonstration Database and Application

The Demonstration Application

END IF END FUNCTION

FUNCTION get_item() DEFINE pa_curr, sc_curr INTEGER LET pa_curr = arr_curr() LET sc_curr = scr_line() SELECT description, unit_price INTO p_items[pa_curr].description, p_items[pa_curr].unit_price FROM stock WHERE stock.stock_num = p_items[pa_curr].stock_num AND stock.manu_code = p_items[pa_curr].manu_code IF status THEN LET p_items[pa_curr].description = NULL LET p_items[pa_curr].unit_price = NULL END IF DISPLAY p_items[pa_curr].description, p_items[pa_curr].unit_price TO s_items[sc_curr].description, s_items[sc_curr].unit_price IF p_items[pa_curr].quantity IS NOT NULL THEN CALL item_total() END IF END FUNCTION

FUNCTION invoice(file_name) DEFINE x_invoice RECORD order_num order_date ship_instruct backlog po_num ship_date ship_weight ship_charge item_num stock_num manu_code quantity total_price description unit_price unit unit_descr manu_name END RECORD, file_name CHAR(20), msg CHAR(40)

LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE

orders.order_num, orders.order_date, orders.ship_instruct, orders.backlog, orders.po_num, orders.ship_date, orders.ship_weight, orders.ship_charge, items.item_num, items.stock_num, items.manu_code, items.quantity, items.total_price, stock.description, stock.unit_price, stock.unit, stock.unit_descr, manufact.manu_name

DECLARE invoice_data CURSOR FOR SELECT o.order_num,order_date,ship_instruct,backlog,po_num,ship_date, ship_weight,ship_charge, item_num,i.stock_num,i.manu_code,quantity,total_price, s.description,unit_price,unit,unit_descr, manu_name FROM orders o,items i,stock s,manufact m WHERE ((o.order_num=p_orders.order_num) AND (i.order_num=p_orders.order_num) AND (i.stock_num=s.stock_num AND i.manu_code=s.manu_code) AND (i.manu_code=m.manu_code)) ORDER BY 9

Demonstration Database and Application

A-31

The Demonstration Application

CASE (print_option) WHEN "f" START REPORT r_invoice TO file_name CALL clear_menu() MESSAGE "Writing invoice -- please wait" WHEN "p" START REPORT r_invoice TO PRINTER CALL clear_menu() MESSAGE "Writing invoice -- please wait" WHEN "s" START REPORT r_invoice END CASE FOREACH invoice_data INTO x_invoice.* OUTPUT TO REPORT r_invoice (p_customer.*, x_invoice.*) END FOREACH FINISH REPORT r_invoice IF print_option = "f" THEN LET msg = "Invoice written to file ", file_name CLIPPED CALL mess(msg, 23) END IF END FUNCTION

REPORT r_invoice (c, x) DEFINE c RECORD LIKE customer.*, x RECORD order_num LIKE orders.order_num, order_date LIKE orders.order_date, ship_instruct LIKE orders.ship_instruct, backlog LIKE orders.backlog, po_num LIKE orders.po_num, ship_date LIKE orders.ship_date, ship_weight LIKE orders.ship_weight, ship_charge LIKE orders.ship_charge, item_num LIKE items.item_num, stock_num LIKE items.stock_num, manu_code LIKE items.manu_code, quantity LIKE items.quantity, total_price LIKE items.total_price, description LIKE stock.description, unit_price LIKE stock.unit_price, unit LIKE stock.unit, unit_descr LIKE stock.unit_descr, manu_name LIKE manufact.manu_name END RECORD, sales_tax, calc_total MONEY(8,2) OUTPUT LEFT MARGIN 0 RIGHT MARGIN 0 TOP MARGIN 1 BOTTOM MARGIN 1 PAGE LENGTH 48

A-32

Demonstration Database and Application

The Demonstration Application

FORMAT BEFORE GROUP OF x.order_num SKIP TO TOP OF PAGE SKIP 1 LINE PRINT 10 SPACES, " W E S T C O A S T W H O L E S A L E R S , I N C ." PRINT 30 SPACES," 1400 Hanbonon Drive" PRINT 30 SPACES,"Menlo Park, CA 94025" SKIP 1 LINES PRINT "Bill To:", COLUMN 10,c.fname CLIPPED, " ", c.lname CLIPPED; PRINT COLUMN 56,"Invoice No. ",x.order_num USING "&&&&&" PRINT COLUMN 10,c.company PRINT COLUMN 10,c.address1 CLIPPED; PRINT COLUMN 56,"Invoice Date: ", x.order_date PRINT COLUMN 10,c.address2 CLIPPED; PRINT COLUMN 56,"Customer No. ", c.customer_num USING "####&" PRINT COLUMN 10,c.city CLIPPED,", ",c.state CLIPPED," ", c.zipcode CLIPPED; PRINT COLUMN 56,"PO No. ",x.po_num PRINT COLUMN 10,c.phone CLIPPED; PRINT COLUMN 56,"Backlog Status: ",x.backlog SKIP 1 LINES PRINT COLUMN 10,"Shipping Instructions: ", x.ship_instruct PRINT COLUMN 10,"Ship Date: ",x.ship_date USING "ddd. mmm dd, yyyy"; PRINT " Weight: ", x.ship_weight USING "#####&.&&" SKIP 1 LINES PRINT "----------------------------------------"; PRINT "---------------------------------------" PRINT " Stock Unit "; PRINT " Item " PRINT " # Num Man Description Qty Cost Unit "; PRINT " Unit Description Total" SKIP 1 LINES LET calc_total = 0.00 ON EVERY ROW PRINT x.item_num USING "#&"," ", x.stock_num USING "&&", " ",x.manu_code; PRINT " ",x.description," ",x.quantity USING "###&", " "; PRINT x.unit_price USING "$$$&.&&"," ",x.unit, " ",x.unit_descr," PRINT x.total_price USING "$$$$$$$&.&&" LET calc_total = calc_total + x.total_price

";

AFTER GROUP OF x.order_num SKIP 1 LINES PRINT "----------------------------------------"; PRINT "---------------------------------------" PRINT COLUMN 50, " Sub-total: ",calc_total USING "$$$$$$$&.&&" LET sales_tax = 0.065 * calc_total LET x.ship_charge = 0.035 * calc_total PRINT COLUMN 45, "Shipping Charge (3.5%): ", x.ship_charge USING "$$$$$$$&.&&" PRINT COLUMN 50, " Sales Tax (6.5%): ",sales_tax USING "$$$$$$$&.&&" PRINT COLUMN 50, " -----------" LET calc_total = calc_total + x.ship_charge + sales_tax PRINT COLUMN 50, " Total: ",calc_total USING "$$$$$$$&.&&" IF print_option = "s" THEN PAUSE "Type RETURN to continue" END IF END REPORT

Demonstration Database and Application

A-33

The Demonstration Application

d4_stock.4gl
GLOBALS "d4_globals.4gl"

FUNCTION stock() MENU "STOCK" COMMAND "Add-stock" "Add new stock items to database" HELP 401 CALL add_stock() COMMAND "Find-stock" "Look up specific stock item" HELP 402 CALL query_stock() COMMAND "Update-stock" "Modify current stock information" HELP 403 CALL update_stock() COMMAND "Delete-stock" "Remove a stock item from database" HELP 404 CALL delete_stock() COMMAND "Exit" "Return to MAIN Menu" HELP 405 CLEAR SCREEN EXIT MENU END MENU END FUNCTION

FUNCTION add_stock() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION query_stock() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION update_stock() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION delete_stock() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

A-34

Demonstration Database and Application

The Demonstration Application

d4_report.4gl
GLOBALS "d4_globals.4gl"

FUNCTION reports() CALL ring_menu() MENU "REPORTS" COMMAND "Labels" "Print mailing labels from customer list" HELP 501 CALL print_labels() CLEAR SCREEN CALL ring_menu() COMMAND "Accounts-receivable" "Print current unpaid orders" HELP 502 CALL print_ar() CLEAR SCREEN CALL ring_menu() COMMAND "Backlog" "Print backlogged orders" HELP 503 CALL print_backlog() CLEAR SCREEN CALL ring_menu() COMMAND "Stock-list" "Print stock available" HELP 504 CALL print_stock() CLEAR SCREEN CALL ring_menu() COMMAND "Options" "Change the report output options" HELP 505 CALL update_options() CALL ring_menu() COMMAND "Exit" "Return to MAIN Menu" HELP 506 CLEAR SCREEN EXIT MENU END MENU END FUNCTION FUNCTION print_labels() DEFINE where_part CHAR(200), query_text CHAR(250), msg CHAR(50), file_name CHAR(20) OPTIONS FORM LINE 7 OPEN FORM customer FROM "custform" DISPLAY FORM customer ATTRIBUTE(MAGENTA) CALL fgl_drawbox(3,30,3,43) CALL fgl_drawbox(3,61,8,7) CALL fgl_drawbox(11,61,8,7) CALL clear_menu() DISPLAY "CUSTOMER LABELS:" AT 1,1 MESSAGE "Use query-by-example to select customer list" CONSTRUCT BY NAME where_part ON customer.* IF int_flag THEN LET int_flag = FALSE ERROR "Label print request aborted" RETURN END IF MESSAGE "" LET query_text = "select * from customer where ", where_part CLIPPED, " order by zipcode" PREPARE label_st FROM query_text DECLARE label_list CURSOR FOR label_st CASE (print_option)

Demonstration Database and Application

A-35

The Demonstration Application

WHEN "f" PROMPT " Enter file name for labels >" FOR file_name IF file_name IS NULL THEN LET file_name = "labels.out" END IF MESSAGE "Printing mailing labels to ", file_name CLIPPED, " -- Please wait" START REPORT labels_report TO file_name WHEN "p" MESSAGE "Printing mailing labels -- Please wait" START REPORT labels_report TO PRINTER WHEN "s" START REPORT labels_report CLEAR SCREEN END CASE FOREACH label_list INTO p_customer.* OUTPUT TO REPORT labels_report (p_customer.*) IF int_flag THEN LET int_flag = FALSE EXIT FOREACH END IF END FOREACH FINISH REPORT labels_report IF int_flag THEN LET int_flag = FALSE ERROR "Label printing aborted" ATTRIBUTE (RED, REVERSE) RETURN END IF IF print_option = "f" THEN LET msg = "Labels printed to ", file_name CLIPPED CALL mess(msg, 23) END IF CLOSE FORM customer OPTIONS FORM LINE 3 END FUNCTION

REPORT labels_report (rl) DEFINE rl RECORD LIKE customer.* OUTPUT TOP MARGIN 0 BOTTOM MARGIN 0 PAGE LENGTH 6 FORMAT ON EVERY ROW SKIP TO TOP OF PAGE PRINT rl.fname CLIPPED, 1 SPACE, rl.lname PRINT rl.company PRINT rl.address1

A-36

Demonstration Database and Application

The Demonstration Application

IF rl.address2 IS NOT NULL THEN PRINT rl.address2 END IF PRINT rl.city CLIPPED, ", ", rl.state, 2 SPACES, rl.zipcode IF print_option = "s" THEN PAUSE "Type RETURN to continue" END IF END REPORT

FUNCTION print_ar() DEFINE r RECORD customer_num fname lname company order_num order_date ship_date paid_date total_price END RECORD, file_name CHAR(20), msg CHAR(50)

LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE

customer.customer_num, customer.fname, customer.lname, customer.company, orders.order_num, orders.order_date, orders.ship_date, orders.paid_date, items.total_price

DECLARE ar_list CURSOR FOR SELECT customer.customer_num,fname,lname,company, orders.order_num,order_date,ship_date,paid_date, total_price FROM customer,orders,items WHERE customer.customer_num=orders.customer_num AND paid_date IS NULL AND orders.order_num=items.order_num ORDER BY 1,5 CALL clear_menu() CASE (print_option) WHEN "f" PROMPT " Enter file name for AR Report >" FOR file_name IF file_name IS NULL THEN LET file_name = "ar.out" END IF MESSAGE "Printing AR REPORT to ", file_name CLIPPED, " -- Please wait" START REPORT ar_report TO file_name WHEN "p" MESSAGE "Printing AR REPORT -- Please wait" START REPORT ar_report TO PRINTER WHEN "s" START REPORT ar_report CLEAR SCREEN MESSAGE "Printing AR REPORT -- Please wait" END CASE

Demonstration Database and Application

A-37

The Demonstration Application

FOREACH ar_list INTO r.* OUTPUT TO REPORT ar_report (r.*) IF int_flag THEN LET int_flag = FALSE EXIT FOREACH END IF END FOREACH FINISH REPORT ar_report IF int_flag THEN LET int_flag = FALSE ERROR "AR REPORT printing aborted" ATTRIBUTE (RED, REVERSE) RETURN END IF IF print_option = "f" THEN LET msg = "AR REPORT printed to ", file_name CLIPPED CALL mess(msg, 23) END IF END FUNCTION REPORT ar_report (r) DEFINE r RECORD customer_num fname lname company order_num order_date ship_date paid_date total_price END RECORD, name_text CHAR(80) OUTPUT PAGE LENGTH 22 LEFT MARGIN 0 FORMAT PAGE HEADER PRINT 15 SPACES,"West Coast Wholesalers, Inc." PRINT 6 SPACES, "Statement of ACCOUNTS RECEIVABLE - ", TODAY USING "mmm dd, yyyy" SKIP 1 LINES LET name_text = r.fname CLIPPED," ",r.lname CLIPPED,"/", r.company CLIPPED PRINT 29 - length(name_text)/2 SPACES, name_text SKIP 1 LINES PRINT " Order Date Order Number Ship Date Amount" PRINT "----------------------------------------------------------" BEFORE GROUP OF r.customer_num SKIP TO TOP OF PAGE AFTER GROUP OF r.order_num NEED 3 LINES PRINT " ",r.order_date,7 SPACES,r.order_num USING "###&",8 SPACES, r.ship_date," ", GROUP SUM(r.total_price) USING "$$$$,$$$,$$$.&&" AFTER GROUP OF r.customer_num PRINT 42 SPACES,"----------------" PRINT 42 SPACES,GROUP SUM(r.total_price) USING "$$$$,$$$,$$$.&&"

LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE LIKE

customer.customer_num, customer.fname, customer.lname, customer.company, orders.order_num, orders.order_date, orders.ship_date, orders.paid_date, items.total_price

A-38

Demonstration Database and Application

The Demonstration Application

PAGE TRAILER IF print_option = "s" THEN PAUSE "Type RETURN to continue" END IF END REPORT FUNCTION update_options() DEFINE po CHAR(2) DISPLAY "Current print option:" AT 8,25 LET po = " ", print_option DISPLAY po AT 8,46 ATTRIBUTE(CYAN) MENU "REPORT OPTIONS" COMMAND "File" "Send all reports to a file" LET print_option = "f" EXIT MENU COMMAND "Printer" "Send all reports to the printer" LET print_option = "p" EXIT MENU COMMAND "Screen" "Send all reports to the terminal screen" LET print_option = "s" EXIT MENU COMMAND "Exit" EXIT MENU END MENU DISPLAY "" AT 8,1 END FUNCTION

FUNCTION print_backlog() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

FUNCTION print_stock() ERROR "This option has not been implemented" ATTRIBUTE (RED) END FUNCTION

Demonstration Database and Application

A-39

The Demonstration Application

d4_demo.4gl
FUNCTION demo() CALL ring_menu() MENU "DEMO" COMMAND "Menus" "Source code for MAIN Menu" CALL showhelp(2001) COMMAND "Windows" "Source code for STATE CODE Window" CALL showhelp(2007) COMMAND "Forms" "Source code for new CUSTOMER data entry" CALL showhelp(2006) COMMAND "Detail-Scrolling" "Source code for scrolling of new ORDER line-items" CALL showhelp(2003) COMMAND "Scroll-Cursor" "Source code for customer record BROWSE/SCROLL" CALL showhelp(2008) COMMAND "Query_language" "Source code for new order insertion using SQL" CALL showhelp(2004) COMMAND "Construct_query" "Source code for QUERY-BY-EXAMPLE selection and reporting" CALL showhelp(2002) COMMAND "Reports" "Source code for MAILING LABEL report" CALL showhelp(2005) COMMAND "Exit" "Return to MAIN MENU" CLEAR SCREEN EXIT MENU END MENU END FUNCTION

A-40

Demonstration Database and Application

The Demonstration Application

helpdemo.src
.101 The Customer option presents you with a menu that allows you to: o o o o Add new customers to the database Locate customers in the database Update customer files Remove customers from the database

.102 The Orders option presents you with a menu that allows you to: o o o o Enter a new order and print an invoice Update an existing order Look up and display orders Remove orders from the database

.103 The Stock option presents you with a menu that allows you to: o o o o Add new items to the list of stock Look up and display stock items Modify current stock descriptions and values Remove items from the list of stock

.104 The Reports option presents you with a menu that allows you to: o o o o o Select and print mailing labels sorted by zip code Print a report of current accounts receivable Print a report of backloged orders Print a list of current stock available Change the report output options

.105 The Exit option leaves the program and returns you to the operating system. .201 The One-add option enables you to enter data on new customers to the database. You may get assistance on what input is appropriate for each field by pressing the function key F1 when the cursor is in the field. When you have entered all the data you want for a given customer, press ESC to enter the data in the database. If you want to abort a given entry and not write it to the database, press the INTERRUPT key (usually DEL or CTRL-C). .202 The Many-add option enables you to enter data on new customers to the database. You may get assistance on what input is appropriate for each field by pressing the function key F1 when the cursor is in the field. When you have entered all the data you want for a given customer, press ESC to enter the data in the database. If you want to abort a given entry and not write it to the database, press the INTERRUPT key (usually DEL or CTRL-C). After each entry, the cursor will move to the beginning of the form and await the entry of the next customer. If you have no more customers to add, press CTRL-Z to return to the CUSTOMER Menu.

Demonstration Database and Application

A-41

The Demonstration Application

.203 The Find-cust option allows you to select one or more customers and to display their data on the screen by using query-by-example input. Use the RETURN or arrow keys to move through the form. Enter the criteria you want the program to use in searching for customers. Your options include: o o o o o Literal values A range of values (separated by ":") A list of values (separated by "|") Relational operators (for example ">105") Wildcards like ? and * to match single or any number of characters

.204 The Update-cust option enables you to alter data on old customers in the database. You must first select a current customer row to deal with by using the Find-cust option. You may get assistance on what input is appropriate for each field by pressing the function key F1 when the cursor is in the field. When you have altered all the data you want for a given customer, press ESC to enter the data in the database. If you want to abort the changes and not write them to the database, press the INTERRUPT key (usually DEL or CTRL-C). .205 The Delete-cust option enables you to remove customers from the database. You must first select a current customer row to deal with by using the Find-cust option. For your protection, you will be asked to confirm that the record should be deleted. Once deleted, it cannot be restored. Customers with active orders can not be deleted. .206 The Exit option of the CUSTOMER Menu takes you back to the MAIN Menu. .301 The Add-order option enables you to add a new order for an existing customer. You must first select the desired customer using query-by-example selection criteria. You will then enter the order date, PO number, and shipping instructions. The detail line items are then entered into a scrolling display array. Up to ten items may be entered using the four line screen array. After the new order is entered, an invoice is automatically generated and displayed on the screen. .302 The Update-order option is currently not implemented. .303 The Find-order option enables you to browse through and select an existing order. You must first select the desired customer (or customers) whos orders you wish to scan. For each customer selected, each corresponding order will be displayed on the screen for examination. You may either select an invoice, skip to the next invoice, or cancel processing.

.304 The Delete-order option is currently not implemented. .305 The Exit option of the ORDER Menu returns you to the MAIN Menu.

A-42

Demonstration Database and Application

The Demonstration Application

.311 You may enter up to ten line items into the scrolling screen array. A number of standard functions are available for manipulating the cursor in a screen array. o o o o o o F1 F2 F3 F4 ESC CTRL-B Insert new line in the screen array Remove the current line from the screen array Page down one page in the screen array Page up one page in the screen array Exit input array When in the Stock Number or Manufacturer Code fields, a window will open in the middle of the screen and display a scrolled list of all items in stock, identified by the stock number and manufacturer. Using F3, F4, and the up and down arrow keys, move the cursor to the line that identifies the desired item and hit ESC. The window will disappear and the selected information will automatically appear in the proper line. The arrow-keys, and the standard field editing keys are available

etc...

The item_total field will be displayed in reverse-video green for total amounts over $500. .401 The Add-stock option is currently not implemented. .402 The Find-stock option is currently not implemented. .403 The Update-stock option is currently not implemented. .404 The Delete-stock option is currently not implemented. .405 The Exit option of the STOCK Menu returns you to the MAIN Menu. .501 The Labels option enables you to create a list of mailing labels generated using a query-by-example specification. You will be prompted for the output file name. .502 The Accounts-receivable option enables you to create a report summarizing all unpaid orders in the database. You will be prompted for the output file name. .503 The Backlog option is currently not implemented. .504 The Stock-list option is currently not implemented. .505 The Options option enables you to change the destination of any report generated during the current session. The default option is to display all reports on the terminal screen. The other options are to print all reports to either the printer or an operating system file. .506 The Exit option of the REPORT Menu returns you to the MAIN Menu.

Demonstration Database and Application

A-43

The Demonstration Application

.1001 The Number field on the Customer Form contains the serial integer assigned to the customer row when the data for the customer is first entered into the database. It is a unique number for each customer. The lowest value of this field is 101. .1002 The first section following the Name label should contain the first name of the contact person at the customers company. .1003 The second section following the Name label should contain the last name of the contact person at the customers company. .1004 This field should contain the name of the customers company. .1005 The first line of the Address section of the form should contain the mailing address of the company. .1006 The second line of the Address section of the form should be used only when there is not sufficient room in the first line to contain the entire mailing address. .1007 The City field should contain the city name portion of the mailing the customer.

address

of

.1008 Enter the two-character code for the desired state. If no code is entered, or the entered code is not in the programs list of valid entries, a window will appear on the screen with a scrolling list of all states and codes. Using the F3, F4, up and down arrow keys, move the cursor to the line containing the desired state. After typing ESC, the window will disappear and the selected state code will appear in the customer entry screen. .1009 Enter the five digit Zip Code in this field. .1010 Enter the telephone number of the contact person at the customers company. Include the Area Code and extension using the format "###-###-#### #####". .2001 The following is the INFORMIX-4GL source for the main menu. Note that only the text is specified by the MENU statement; the structure and runtime menu functions are built-in. OPTIONS HELP FILE "helpdemo" OPEN FORM menu_form FROM "ring_menu" DISPLAY FORM menu_form MENU "MAIN" COMMAND "Customer" "Enter and maintain customer data" HELP 101 CALL customer() DISPLAY FORM menu_form COMMAND "Orders" "Enter and maintain orders" HELP 102 CALL orders() DISPLAY FORM menu_form COMMAND "Stock" "Enter and maintain stock list" HELP 103 CALL stock() DISPLAY FORM menu_form

A-44

Demonstration Database and Application

The Demonstration Application

COMMAND "Reports" "Print reports and mailing labels" HELP 104 CALL reports() DISPLAY FORM menu_form COMMAND "Exit" "Exit program and return to operating system" HELP 105 CLEAR SCREEN EXIT PROGRAM END MENU .2002 The following is the INFORMIX-4GL source code for mailing-label selection and printing. The CONSTRUCT statement manages the query-by-example input and builds the corresponding SQL where-clause. CONSTRUCT BY NAME where_part ON customer.* LET query_text = "select * from customer where ", where_part CLIPPED, " order by zipcode" PREPARE mail_query FROM query_text DECLARE label_list CURSOR FOR mail_query PROMPT "Enter file name for labels >" FOR file_name MESSAGE "Printing mailing labels to ", file_name CLIPPED," -- Please wait" START REPORT labels_report TO file_name FOREACH label_list INTO p_customer.* OUTPUT TO REPORT labels_report (p_customer.*) END FOREACH FINISH REPORT labels_report See the source code option REPORT for the corresponding report routine. .2003 The following is the INFORMIX-4GL source code for order entry using scrolled input fields. Only the INPUT ARRAY statement in needed to utilize the full scrolling features. Some additional code has been added merely to customize the array processing to this application. DISPLAY "Press ESC to write order" AT 1,1 INPUT ARRAY p_items FROM s_items.* HELP 311 BEFORE FIELD stock_num MESSAGE "Enter a stock number." BEFORE FIELD manu_code MESSAGE "Enter the code for a manufacturer." AFTER FIELD stock_num, manu_code LET pa = arr_curr() LET sc = scr_line() SELECT description, unit_price INTO p_items[pa].description, p_items[pa].unit_price FROM stock WHERE stock_num = p_items[pa].stock_num AND stock_manu = p_items[pa].menu_code DISPLAY p_items[pa].description, p_items[pa].unit_price TO stock[sc].* CALL item_total() AFTER FIELD quantity CALL item_total() AFTER INSERT, DELETE, ROW CALL order_total() END INPUT See the source code option QUERY-LANGUAGE for the SQL statements that insert the order information into the database.

Demonstration Database and Application

A-45

The Demonstration Application

.2004 The following is the INFORMIX-4GL source code that uses SQL to insert the entered order information into the database. Note that the use of transactions ensures that database integrity is maintained, even if an intermediate operation fails. BEGIN WORK LET p_orders.order_num = 0 INSERT INTO orders VALUES (p_orders.*) IF status < 0 THEN ROLLBACK WORK MESSAGE "Unable to complete update of orders table" RETURN END IF LET p_orders.order_num = SQLCA.SQLERRD[2] DISPLAY BY NAME p_orders.order_num FOR i = 1 to arr_count() INSERT INTO items VALUES (p_items[counter].item_num, p_orders.order_num, p_items[counter].stock_num, p_items[counter].manu_code, p_items[counter].quantity, p_items[counter].total_price) IF status < 0 THEN ROLLBACK WORK Message "Unable to insert items" RETURN FALSE END IF END FOR COMMIT WORK .2005 The following is the INFORMIX-4GL source code that generates the mailing-label report. See the source code option CONSTRUCT for the report calling sequence. REPORT labels_report (rl) DEFINE rl RECORD LIKE customer.* OUTPUT TOP MARGIN 0 PAGE LENGTH 6 FORMAT ON EVERY ROW SKIP TO TOP OF PAGE PRINT rl.fname CLIPPED, 1 SPACE, rl.lname PRINT rl.company PRINT rl.address1 IF rl.address2 IS NOT NULL THEN PRINT rl.address2 END IF PRINT rl.city CLIPPED, ", ", rl.state, 2 SPACES, rl.zipcode END REPORT

.2006 The following is the INFORMIX-4GL source code that manages a simple form for data entry. Note the use of special key definitions during data entry. OPEN FORM cust_form FROM "customer" DISPLAY FORM cust_form MESSAGE "Press F1 or CTRL-F for field help;", "F2 or CTRL-Z to return to CUSTOMER Menu" DISPLAY "Press ESC to enter new customer data or DEL to abort entry" INPUT BY NAME p_customer.* AFTER FIELD state CALL statehelp() ON KEY (F1, CONTROL-F)

A-46

Demonstration Database and Application

The Demonstration Application

CALL customer_help() ON KEY (F2, CONTROL-Z) CLEAR FORM RETURN END INPUT .2007 The following is the INFORMIX-4GL source code that opens a window in the customer entry screen, displays the list of valid state names and codes, saves the index into the p_state array for the selected state, closes the window, and returns the index to the calling routine. OPEN WINDOW w_state AT 8,40 WITH FORM "state_list" ATTRIBUTE (BORDER, RED, FORM LINE 2) CALL set_count(state_cnt) DISPLAY ARRAY p_state TO s_state.* LET idx = arr_curr() CLOSE WINDOW w_state RETURN (idx) .2008 The following is the INFORMIX-4GL source code that allows the user to browse through the rows returned by a "scroll" cursor. DECLARE customer_set SCROLL CURSOR FOR SELECT * FROM customer ORDER BY lname OPEN customer_set FETCH FIRST customer_set INTO p_customer.* IF status = NOTFOUND THEN LET exist = FALSE ELSE LET exist = TRUE DISPLAY BY NAME p_customer.* MENU "BROWSE" COMMAND "Next" "View the next customer in the list" FETCH NEXT customer_set INTO p_customer.* IF status = NOTFOUND THEN ERROR "No more customers in this direction" FETCH LAST customer_set INTO p_customer.* END IF DISPLAY BY NAME p_customer.* COMMAND "Previous" "View the previous customer in the list" FETCH PREVIOUS customer_set INTO p_customer.* IF status = NOTFOUND THEN ERROR "No more customers in this direction" FETCH FIRST customer_set INTO p_customer.* END IF DISPLAY BY NAME p_customer.* COMMAND "First" "View the first customer in the list" FETCH FIRST customer_set INTO p_customer.* DISPLAY BY NAME p_customer.* COMMAND "Last" "View the last customer in the list"

Demonstration Database and Application

A-47

The Demonstration Application

FETCH LAST customer_set INTO p_customer.* DISPLAY BY NAME p_customer.* COMMAND "Select" "Exit BROWSE selecting the current customer" LET chosen = TRUE EXIT MENU COMMAND "Quit" "Quit BROWSE without selecting a customer" LET chosen = FALSE EXIT MENU END MENU END IF CLOSE customer_set

A-48

Demonstration Database and Application

Appendix

System Catalogs
Information about the database is maintained in the system catalogs. The system catalogs are as follows: systables syscolumns sysindexes systabauth syscolauth sysdepend syssynonyms sysusers sysviews sysconstraints syssyntable describes database tables. describes columns in tables. describes indexes on columns. identies table-level privileges. identies column-level privileges. describes how views depend on tables. lists synonyms for tables. identies database-level privileges. denes views. records constraints placed on database tables. used for mapping of synonyms.

The following list gives a brief description of the system catalogs.

The SYSTABLES Catalog

The SYSTABLES Catalog

Column Name tabname owner dirpath tabid rowsize ncols nindexes nrows created version tabtype audpath Index Name tabname tabid Type char(18) char(8) char(64) serial smallint smallint smallint integer date integer char(1) char(64) Type unique unique Explanation name of table owner of table directory path for the table le internal table identier row size number of columns number of indexes number of rows date created table version number table type (T = table, V = view, S = synonym) audit lename (full pathname) Columns tabname, owner tabid

The SYSCOLUMNS Catalog

Column Name colname tabid colno coltype collength Index Name column Type char(18) integer smallint smallint smallint Type unique Explanation column name table identier column number column type column length (physical) Columns tabid, colno

B-2

System Catalogs

The SYSINDEXES Catalog

The SYSINDEXES Catalog

Column Name idxname owner tabid idxtype clustered part1 part2 part3 part4 part5 part6 part7 part8 Index Name idxtab idxname Type char(18) char(8) integer char(1) char(1) smallint smallint smallint smallint smallint smallint smallint smallint Type dupls unique Explanation index name owner of index table identier index type (U = unique, D = dupls) clustering column number column number column number column number column number column number column number column number Columns tabid idxname, tabid

The SYSTABAUTH Catalog

Column Name grantor grantee tabid tabauth Index Name tabgtor tabgtee Type char(8) char(8) integer char(7) Type unique dupls Explanation grantor of permission grantee (receiver) of permission table identier authorization type Columns tabid, grantor, grantee tabid, grantee

The SYSCOLAUTH Catalog

Column Name grantor grantee tabid colno colauth Type char(8) char(8) integer smallint char(2) Explanation grantor of permission grantee (receiver) of permission table identier column number authorization type

System Catalogs

B-3

The SYSDEPEND Catalog

Index Name colgtor colgtee

Type unique dupls

Columns tabid, grantor, grantee, colno tabid, grantee

The SYSDEPEND Catalog

Column Name btabid btype dtabid dtype Index Name btabid dtabid Type integer char(1) integer char(1) Type dupls dupls Explanation tabid of base table or view base object type (table or view) tabid of dependent table dependent object type (only view now) Columns btabid dtabid

The SYSSYNONYMS Catalog

Column Name owner synonym created tabid Index Name synonym syntabid Type char(8) char(18) date integer Type unique dupls Explanation user name of owner synonym identier date synonym created table identier Columns owner, synonym tabid

The SYSUSERS Catalog

Column Name username usertype priority password Index Name users Type char(8) char(1) smallint char(8) Type unique Explanation user login identier D = DBA, R = RESOURCE, C = CONNECT reserved for future use reserved for future use Columns username

B-4

System Catalogs

The SYSVIEWS Catalog

The SYSVIEWS Catalog

Column Name tabid seqno viewtext Index Name view Type integer smallint char(64) Type unique Explanation table identier sequence number portion of SELECT statement Columns tabid, seqno

The SYSCONSTRAINTS Catalog

Column Name Type constrid serial constrname char(18) owner char(8) tabid integer constrtype char(1) idxname char(18) Index Name Type constrname unique constrtabid dupls constrid unique Explanation reserved for future use constraint identier user name of owner table identier reserved for future use index name Columns constrname, owner tabid constrid

The SYSSYNTABLE Catalog

Column Name Type tabid integer turboname dbname tabname owner btabid integer Index Name Type synntabid unique synnbtabid dupls Explanation table identier used on INFORMIX-OnLine only used on INFORMIX-OnLine only used on INFORMIX-OnLine only used on INFORMIX-OnLine only tabid of base table or view Columns tabid btabid

System Catalogs

B-5

The SYSSYNTABLE Catalog

B-6

System Catalogs

Appendix

Environment Variables
INFORMIX-4GL makes the following assumptions about the users environment:

The editor used is the predominant operating system

editor (usually vi).

The database worked with is in the current directory. The program that sends les to the printer is lp. You use /tmp to store temporary les. The INFORMIX-4GL program and its associated les are located in /usr/informix.

Setting Environment Variables

Setting Environment Variables

You can change any of the assumptions by setting one or more of the environment variables recognized by INFORMIX-4GL. You can set environment variables at the system prompt or in your .prole (Bourne shell) or .login (C shell) le. If you set an environment variable at the system prompt, you will have to assign it again the next time you log onto the system. If you set a variable in your .prole (Bourne shell) or .login (C shell) le, UNIX will assign it automatically every time you log onto the system. If you are using the Bourne shell, enter the following two commands to set the ABCD environment variable to value:
ABCD=value export ABCD

If you are using the C shell, enter the following command to set the ABCD environment variable to value:
setenv ABCD value INFORMIX-4GL recognizes the following environment variables:

DBANSIWARN
DBANSIWARN species that you want to initiate Informix extension checking. Setting the DBANSIWARN environment variable before you compile a 4GL program is functionally equivalent to compiling with the -ansi ag. When Informix extensions to ANSI standard syntax are encountered in your program, warning messages are written to a .err le. At run time, the DBANSIWARN environment variable causes SQLAWARN[6] to be set to W when a non-ANSI statement is executed.

Unlike most environment variables, you do not set DBANSIWARN to a value. Simply setting it in the environment is sufcient. Set the DBANSIWARN environment as follows:

C shell:
setenv DBANSIWARN

Bourne shell:
DBANSIWARN= export DBANSIWARN

C-2

Environment Variables

DBDELIMITER

Once you have set DBANSIWARN, Informix extension checking is automatic until you logout or unset DBANSIWARN. When you want to turn off Informix extension checking, you can unset the DBANSIWARN environment variable using the following commands.

C shell:
unsetenv DBANSIWARN

Bourne shell:
unset DBANSIWARN

DBDELIMITER
DBDELIMITER species the eld delimiter used by the dbload utility in unloaded data les. The vertical bar ( | = ASCII 124) is the default.

For example, to make plus ( + ) the eld delimiter on a C shell system, enter:
setenv DBDELIMITER +

DBDATE
DBDATE species the format you want to use for DATE values. Through DBDATE, you can specify

The order of the month, day, and year in a date Whether the year should be printed with two digits (Y2) or four digits
(Y4)

The separator between the month, day, and year

The default value for DBDATE is
MDY4/

where M represents the month, D represents the day, Y4 represents a fourdigit year, and the separator is a (/) slash (mm/dd/yyyy). Other acceptable values for the separator are a hyphen ( - ), a period ( . ), or a zero ( 0 ). (You use the zero to indicate no separator.) The slash appears if you attempt to use a value other than the hyphen, period, or zero to indicate the separator, or if you do not include a separator character in the DBDATE denition.

Environment Variables C-3

DBEDIT

The separator value must always be specied last. The number of digits specied for the year must always follow the Y. To make the date appear as mmddyy (with no separator), you would set the DBDATE environment variable for the C shell as follows:
setenv DBDATE MDY20

For the Bourne shell, you would use

DBDATE=MDY20 export DBDATE

Suppose that you wanted the date to appear in European format (dd-mm-yyyy). For the C shell, you would set the DBDATE environment variable as follows:
setenv DBDATE DMY4-

For the Bourne shell, you would use

DBDATE=DMY4export DBDATE

DBEDIT
DBEDIT names the text editor for creating program les, form specication les, and command les from within the INFORMIX-4GL Programmers

Environment. For most systems, the default is vi.

DBLANG
DBLANG species the subdirectory of $INFORMIXDIR that contains the message (.iem) les used by your program. The default is $INFORMIXDIR/msg.

C-4

Environment Variables

DBMONEY

If you want to use a message directory other than $INFORMIXDIR/msg, perform the following steps: 1. Use the mkdir command to create the appropriate subdirectory in $INFORMIXDIR. Set the user and group to informix and the access permission for this directory to 755. 2. Set the DBLANG environment variable to the new subdirectory. (Specify only the name of the subdirectory and not the full pathname of the subdirectory.) If you are using the Bourne shell, enter
DBLANG=dirname export DBLANG

If you are using the C shell, enter

setenv DBLANG dirname

3. Copy the .iem les to the message directory specied by $INFORMIXDIR/ $DBLANG. All les in the message directory should have user and group informix and 644 access permission. 4. Run your program.

DBMONEY
DBMONEY applies to MONEY values. It has the format [ front ] { . | , } [ back ]

where front is the optional symbol that precedes the MONEY value, the comma or the period is the optional symbol that separates the integral from the fractional part of the MONEY value, and back is the optional symbol that follows the MONEY value. The front and back symbols can be up to seven characters long and can contain any characters except commas or periods. The default value for DBMONEY is
$.

where the dollar sign precedes the MONEY value, and the period (.) separates the integral from the fractional part of the MONEY value. (No back symbol appears.) Suppose you wanted to represent MONEY values in deutsche marks. For the C shell, you would set the DBMONEY environment variable as follows:
setenv DBMONEY DM,

Environment Variables C-5

DBPATH

For the Bourne shell, you would use

DBMONEY=DM, export DBMONEY

where DM is the currency symbol, and the comma separates the integral from the fractional part of the MONEY value. If you have specied both symbols and you make a change to either one, you must respecify the other symbol and the value separator (comma or period). Similarly, if you change the value separator from a comma to a period, you must respecify the front symbol as well as the back symbol (if you had previously specied a back symbol).

DBPATH
DBPATH species a list of directories (in addition to the current directory) for INFORMIX-4GL to search for databases and associated les. If you have not selected a database, INFORMIX-4GL looks to DBPATH as well as the current

directory to determine the list of available databases. Once you have selected a database, INFORMIX-4GL looks rst in the current directory and then in the parent directory of the directory containing the database (recall that each database is contained in a separate directory) for the associated forms, reports, and command les. For example, if you want INFORMIX-4GL to search for database les in Kevins and Zooies directories, as well as in your current directory, you would specify
DBPATH=/usr/Kevin:/usr/Zooie export DBPATH

Make sure you enter a colon between the directory names.

DBPRINT
DBPRINT species the print program for your computer. For most UNIX systems, the default program is lp.

DBTEMP
DBTEMP species the directory into which INFORMIX-4GL should place its

temporary les. The default is the /tmp directory.

C-6

Environment Variables

INFORMIXDIR

INFORMIXDIR
INFORMIXDIR species the directory containing the INFORMIX-4GL les. The default is the /usr/informix directory.

INFORMIXTERM
INFORMIXTERM species whether INFORMIX-4GL should use the termcap or

terminfo les to locate terminal capability information. If you do not set

INFORMIXTERM, INFORMIX-4GL uses termcap.

If you are using the Bourne shell, enter:

INFORMIXTERM=type export INFORMIXTERM

where type is termcap or terminfo. If you are using the C shell, enter:
setenv INFORMIXTERM=type

SQLEXEC
SQLEXEC is needed only if you have both INFORMIX-SE and INFORMIX-OnLine installed on your system, and you want to access INFORMIX-SE. If you have both engines installed, but you do not specify SQLEXEC, then INFORMIX-OnLine is the default engine. SQLEXEC must contain the full pathname of the database engine, which is located in the lib subdirectory of $INFORMIXDIR.

To use INFORMIX-OnLine with the Bourne shell, specify:

SQLEXEC=$INFORMIXDIR/lib/sqlturbo export SQLEXEC

To use INFORMIX-SE with the Bourne shell, specify:

set SQLEXEC=$INFORMIXDIR/lib/sqlexec export SQLEXEC

To use INFORMIX-OnLine with the C shell, specify:

setenv SQLEXEC $INFORMIXDIR/lib/sqlturbo

To use INFORMIX-SE with the C shell, specify:

setenv SQLEXEC $INFORMIXDIR/lib/sqlexec

Environment Variables C-7

SQLEXEC

C-8

Environment Variables

Appendix

Reserved Words
This appendix contains a list of Informix reserved words. Do not use these words as identiers or as program variable or host variable names. If you use reserved words as identiers or variables, your program (or SQL statement) may fail with an error. This list contains reserved words from all Informix products, although not all are reserved in each product. Note that, while their use is not recommended, some reserved words may not cause errors in every case. For example, words that are reserved in INFORMIX-4GL will not generate an error if used with only INFORMIX-SQL. However, if your INFORMIX-SQL application is later ported to an INFORMIX-4GL environment, any INFORMIX-4GL reserved words will cause errors. Additionally, some words only generate errors if used as host or program variables, while other words only generate errors if used as identiers. In addition to the words on this list, you should not use C, ADA, or COBOL language keywords in your programs.

abort absolute accept access add after all allowing alter and ansi any array as asc ascending ascii at attribute attributes audit auto autonext average avg background before begin beginning bell between black blanks blink blue bold border bottom buffered by byte call case
D-2 Reserved Words

char character check clear clipped close cluster col color colors column columns command comment comments commit committed composites compress connect constant constraint construct continue convert count create current cursor cyan database date datetime date_type day dba debug dec decimal decimal_type declare dec_t default

defaults defer define delete delimiter delimiters desc descending describe descriptor dim dirty display displayonly distinct do dominant double down downshift drop dtime dtime_t eco-* editadd editupdate else end end-exec endif ending error escape every exclusive exec execute exists exit exitnow exits explain extend

extent extern external false fetch field file finish first fixchar float flush for foreach form format formonly found fraction free from function globals go go to goto grant green group having header headings help hold hour identified if ifdef ifndef immediate in include index

indicator infield info initialize input insert instructions int integer interrupt intersect interval into intrvl_t inverse invisible is isam isolation join joining key label last left len length let like line lineno lines load locator lock loc_t log long long_float long_integer lookup loop magenta

main margin master matches max mdy memory menu message min minus minute mod mode modify module money month name natural need new next nextfield no nocr noentry normal not not found notfound noupdate now null numeric of off on open option options or order

otherwise out outer output package page pageno param pause percent perform picture pipe positive precision prepare previous print printer prior privilege privileges program prompt public put query queryclear quit raise range read readonly real record recover red register relative remove rename repair repeatable

report required resource return returning reverse revoke right rollback rollforward row rowid rows run savepoint screen scroll second section select serial serial_type set share shift short short_float short_integer sitename size skip sleep smallfloat smallint some space spaces sql sql* sqlca sqlchar_type sqlda sqldecimal_type
Appendix D: Reserved Words 3

sqlerr sqlerror sqlfloat_type sqlint_type sqlmoney_type sqlsmfloat_type sqlsmint_type sqlwarning stability start startlog static statistics status stdv step stop string struct subtract

subtype sum synonym systables table temp text then through thru time tiny_integer to today top total trailer trailing true type

typedef undef underline union unique units unload unlock up update upshift user using validate values varchar variable vc_t verify view

wait waiting warning weekday when whenever where while white window with without wordwrap work wrap year yellow yes zerofill

D-4

Reserved Words

Appendix

INFORMIX-4GL Utility Programs

This appendix describes nine utility programs that are included with the INFORMIX-4GL software. You can invoke these utilities at the system prompt to perform any of the following tasks:

The bcheck utility checks and restores the integrity of

your index les.

The dbload utility allows you to load data from other

database systems or from raw data les into INFORMIX-4GL databases.

The dbexport utility allows you to unload a database

into ASCII les.

The dbimport utility allows you to create a database

from appropriate ASCII les. The dbschema utility allows you to output the SQL statements necessary to replicate an individual table or an entire database. The dbupdate utility updates an SQL Version 1 database to an SQL Version 2 database. The mkmessage utility compiles programmer-dened help messages for INFORMIX-4GL applications. The sqlconv utility converts an INFORMIX database to an SQL-compatible database. The upscol utility enables you to establish default attributes for display elds that are linked to database columns in your screen forms. It can also establish initial default values for program variables and screen elds that you associate with columns of tables in your database.

The bcheck Utility

The bcheck Utility

For every database table, INFORMIX-4GL creates two les in the database directory. These les have names consisting of a few characters of the table name, a unique number (starting at 100), and a lename extension. The extension .dat identifes the data le, while the extension .idx identies the index le. In the stores database, for instance, data in the customer table is stored in a le named custome100.dat, while a le named custome100.idx contains the table indexes. To identify the actual lenames that INFORMIX-4GL has assigned on your system, you can examine the stores.dbs directory, where both les reside. Should these les be damaged, you may experience symptoms ranging from sluggish performance to seemingly missing data. The bcheck utility, supplied with INFORMIX-4GL on INFORMIX-SE, can verify the integrity of both les and repair and rebuild corrupted indexes. If you have used INFORMIX-4GL only as described in your manual and have not intentionally modied these les in some other way, any damage is normally due either to power uctuations or to hardware problems in your mass storage system. The bcheck utility compares an index le to a data le to see whether the two are consistent. If they are not, bcheck asks whether you want each damaged index to be deleted and rebuilt. For each index, bcheck prints a group of up to eight numbers. These numbers indicate the position of the key in each record. In running bcheck, you must specify the table name as it exists in the database directory (custome100, for example, instead of customer). The following example runs bcheck, with the -n option, on the customer table.
bcheck -n custome100

E-2

INFORMIX-4GL Utility Programs

The bcheck Utility

In the example on the next page of output from this command line, bcheck nds no errors.
BCHECK C-ISAM B-tree Checker version 4.00.00 Copyright (C) 1981-1989 Informix Software, Inc. Software Serial Number INF#R000000

C-ISAM File: custome100 Checking dictionary and file sizes. Index file node size = 1024 Current C_ISAM index file node size = 1024 Checking data file records. Checking indexes and key descriptions. Index 1 = unique key 0 index node(s) used -- 1 index b-tree level(s) used Index 2 = unique key (0,4,2) 1 index node(s) used -- 1 index b-tree level(s) used Index 3 = duplicates (111,5,0) 1 index node(s) used -- 1 index b-tree level(s) used Checking data record and index node free lists. 4 index node(s) used, 0 free -- 18 data record(s) used, 4 free

You can also run bcheck with the following options: -i -l -n -y -q -s Check index le only List entries in B+ trees Answer no to all questions Answer yes to all questions Suppress printing of the program banner Resize the index le node size

The bcheck command syntax is as follows:

bcheck -[i | l | y | n | q | s] lename

Unless you use the -n or -y option, bcheck is interactive, waiting for you to respond to each error that it nds. Use the -y option with caution. Do not run bcheck using the -y option if you are checking the les for the rst time.

INFORMIX-4GL Utility Programs

E-3

The bcheck Utility

Here is an example of bcheck output in which bcheck nds errors. The -n option is selected, so that each question bcheck asks is automatically answered no.
BCHECK C-ISAM B-tree Checker version 4.00.00 Copyright (C) 1981-1989 Informix Software, Inc. Software Serial Number INF#R000000

C-ISAM File: custome100 Checking dictionary and file sizes. Index file node size = 1024 Current C_ISAM index file node size = 1024 Checking data file records. Checking indexes and key descriptions. Index 1 = unique key 0 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? no Index 2 = unique key (0,4,2) 1 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? no Index 3 = duplicates (111,5,0) 1 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? no Checking data record and index node free lists. ERROR: 3 missing data record(s) Fix data record free list ? no 4 index node(s) used, 0 free -- 18 data record(s) used, 4 free

Since bcheck nds errors, you must delete and rebuild the corrupted indexes.

E-4

INFORMIX-4GL Utility Programs

The bcheck Utility

The -y option is used to answer yes to all questions asked by bcheck:

BCHECK C-ISAM B-tree Checker version 4.00.00 Copyright (C) 1981-1989 Informix Software, Inc. Software Serial Number INF#R000000

C-ISAM File: custome100 Checking dictionary and file sizes. Checking data file records. Checking indexes and key descriptions. Index 1 = unique key 1 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? yes Remake index ? yes Index 2 = unique key (0,4,2) 1 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? yes Remake index ? yes Index 3 = duplicates (111,5,0) 1 index node(s) used -- 1 index b-tree level(s) used ERROR: 3 bad data record(s) Delete index ? yes Remake index ? yes Checking data record and index node free lists. ERROR: 3 missing data record(s) Fix data record free list ? yes Recreate Recreate Recreate Recreate data record free list index 3 index 2 index 1

4 index node(s) used, 0 free -- 18 data record(s) used, 4 free

You can run bcheck as often as you like.

INFORMIX-4GL Utility Programs

E-5

The dbexport Utility

The dbexport Utility

Overview
Use dbexport to unload a database into ASCII les for import into another database environment.

Syntax
dbexport [ -c ] [ -q ] database [ -o directory-path | -t device -b blksize -s tapesize [ -f pathname ] ]

Explanation
dbexport -c -q database -t device -b blksize -s tapesize -f pathname is the program name. tells the program to continue even though errors occur. tells the program not to display anything on its standard output. is the name of the database to be exported. directs the output to a specied tape device. species the tape block size in kilobytes. species the capacity of one tape reel. tells the program to write data denition statements to the le pathname and not to the tape.

-o directory-path directs the output to a specied directory on disk.

Notes
1. You must have DBA privilege or log in as user informix to export a database. 2. The database is locked in exclusive mode during export. If an exclusive lock cannot be obtained, the program ends with a diagnostic message. 3. The dbexport program always creates a le of messages called dbexport.out. This le contains any error messages and warnings, and it also contains a display of the SQL data denition statements that it is generating. The same material is also written to the standard output unless you specify the -q option.

E-6

INFORMIX-4GL Utility Programs

The dbexport Utility

4. You can cancel the program with an Interrupt signal. The dbexport program asks for conrmation before terminating. 5. The dbexport program writes multiple les containing database data, either to disk or to tape. The -t option species that the destination is a tape drive; otherwise, dbexport writes the les to disk. When you include the -t option, you must also specify the tape device, the block size, and the volume capacity. 6. When you include the -t option, the le of data denition statements and other commands (used by the dbimport utility) are ordinarily also written to the tape. Use the -f option to instruct the program to write these to the le pathname. This allows you to inspect and modify the statements. 7. When you do not include the -t option, the destination is a disk directory with the name database.exp. This directory must not exist; the program will create it. Its group will be informix. If you include the -o directorypath option, the database.exp directory is located in the specied directory. By default, the database is placed in your current working directory. 8. When output is to disk, the le containing the data denition statements and other commands to dbimport is written to the le database.sql in the database.exp directory.

Examples
The following command exports the stores database to tape with a block size of 16 kilobytes and a tape capacity of 24,000 kilobytes. The le of data denition statements and other directions to dbimport is written to stores.imp in the /tmp directory.
dbexport -c stores -t /dev/rmt0 -b 16 -s 24000 -f /tmp/stores.imp

The following command exports the stores database to the /usr/informix/port/stores.exp directory.
dbexport -c stores -o /usr/informix/port INFORMIX-OnLine supports additional functionality. Refer to the INFORMIXOnLine Programmers Manual for more information.

INFORMIX-4GL Utility Programs

E-7

The dbimport Utility

The dbimport Utility

Overview
Use dbimport to create a database from ASCII les.

Syntax
dbimport [-c] [-q] database [-i directory-path |-t device -b blksize -s tapesize [-f pathname] ] [-d dbspace] [-l [ logpath | buffered] ] [-ansi]

Explanation
-c -q database -t device -b blksize -s tapesize -f pathname -d dbspace -l logpath buffered -ansi tells the program to continue even when errors occur, unless it is a fatal error. tells the program not to display anything on its standard output. is the name of the database to import. species input from a particular tape device. species the tape block size in Kbytes. species the capacity of one tape reel. tells the program to read data denition statements from the le pathname and not from the tape. when importing to INFORMIX-OnLine only, species the dbspace where the new database is to go. species that the imported database is to use transaction logging. when importing to the standard database engine only, species the pathname of the transaction log le. when importing to INFORMIX-OnLine only, species buffered or unbuffered logging (unbuffered is the default). tells the program to create the new database as MODE ANSI.

-i directory-path species the path to an input directory.

E-8

INFORMIX-4GL Utility Programs

The dbimport Utility

Notes
1. The program always creates a message le called dbimport.out in the current directory. This le contains messages and warnings related to the running of the program. The message are also written to the standard output (normally the terminal screen) unless you include the -q option. 2. You can cancel the program with an interrupt signal. You are prompted for conrmation before the program terminates. 3. The individual who runs dbimport is granted DBA privilege on the new database. 4. When importing a database that uses the standard database engine, database les are created in the current directory. 5. Use the -l option to establish transaction logging for the imported database. This option is equivalent to the WITH LOG IN clause of the CREATE DATABASE statement. A database created as MODE ANSI requires transaction logging. In this situation, you must include the -l option. 6. The dbimport utility reads multiple les containing database data from either disk or tape. Use the -t option to specify the source as tape; the default is disk. When you include the -t option, you must also specify the tape device, blocksize and volume capacity. 7. When you include the -t option, dbimport reads the data denition statements and other dbimport commands from the tape. Use the -f pathname option to instruct the program to read the database.sql le in pathname (instead of the tape) for the data denition statements and other commands. To use the -f option you must have also used it when you executed the dbexport program. 8. If you do not specify the -t option, the source of the database data is a disk directory with the name database.exp. The dbimport program looks for this directory in the current working directory, or on the path specied with the -i option. In either case, the program takes data denition and other commands from the le database.sql in the directory database.exp. (This is why the name database must be the same as was given to dbexport.)

INFORMIX-4GL Utility Programs

E-9

The dbimport Utility

Example
The following command imports the stores database from a tape with a blocksize of 16 Kbytes and capacity of 24,000 Kbytes. The le of data denition statements and other import commands was put in stores.imp in the /tmp directory when dbexport was run.
dbimport -c stores -t /dev/rmt0 -b 16 -s 24000 -f /tmp/stores.imp

The following command imports the stores database from the /usr/informix/ port/stores.exp directory using data denition and commands from the le stores.sql in that directory. The new database is created as MODE ANSI and uses logging.
dbimport -c stores -i /usr/informix/port -ansi -l /usr/work/stores.log

INFORMIX-OnLine supports additional functionality. Refer to the INFORMIXOnLine Programmers Manual for more information.

E-10

INFORMIX-4GL Utility Programs

The dbload Utility

The dbload Utility

The dbload utility provides a method for transferring data from ASCII les into an existing database. This program supports the easy and efcient transfer of database les created for other Informix products, or even for entirely different database management systems. The dbload utility includes the following features:

Data from selected elds of one or more input les can be loaded into
selected columns of one or more database tables.

Loading can begin at any line in the input le. Loading proceeds in batches of n records (where n is an integer that you
specify).

Both xed- and variable-length data records can be loaded. NULL values can be dened for any eld of a record. Constants that are not in the data records can be loaded. Records that cannot be loaded into the database are trapped and stored
(with diagnostic information) in an error log le.

The user can specify an error limit, and dbload stops when that limit is
reached on the number of records that cannot be entered into the database because of errors.

If your database supports transactions, you have the option of terminating the loading process without committing any data from the batch of records that exceeded your error limit. To use dbload, you must have at least one ASCII input le of data records to enter, and at least one table to receive the data. You must then create a command le to specify instructions for reading and loading the data. Finally, you must invoke dbload by entering an appropriate command line. The following sections provide details about these procedures.

Input Files for the dbload Utility

Just as database tables store data in columns within rows, input le data must be arranged in elds within records. You must be able to specify a one-to-one correspondence between elds of the input records and columns of the new rows that dbload will insert in the database. Data les for dbload must be at ASCII les, containing only printable characters. The records containing the data to be transferred must be separated by the NEWLINE character. Output from the UNLOAD statement of SQL, for example, can be used as an input le by dbload.
INFORMIX-4GL Utility Programs E-11

The dbload Utility

Fixed-Length and Variable-Length Records

The record length can be either xed or variable. An input le has xed-length records if the locations of data elds and the number of characters are the same across all records. If a le has variable-length records, every eld must end with the same delimiter character (which must not occur as data within any eld). This character does not need to be the same one that the DBDELIMITER environment variable species. Two consecutive delimiters in a variable-length record dene a NULL eld. For each eld in a xed-length record, you can use the dbload command le to specify a character string to store as a NULL value.

Data Type Formats

Leading blanks are allowed in data elds. A currency symbol is optional in data elds for MONEY columns. Values of type DATE must be in mm / dd / yyyy format. Data for DATETIME and INTERVAL columns must be in character form, showing only eld digits and delimiters (no type or qualiers):
yyyy - mm - dd hh : mi : ss . fff

Here yyyy represents year digits, mm the month (January = 1 or 01), dd the day of the month, hh the hour, mi the minute, ss the second, and fff the fractional part of a second.

Specifying a dbload Command File

Before you can use dbload, you must rst create an ASCII command le that maps elds from one or more input les into columns of one or more tables within your database. This command le must specify two kinds of information:

One or more FILE statements, to dene data elds within the records of
the input le(s)

One or more INSERT statements, to indicate how to place the new data
into the columns of the database table(s)
INSERT statements in dbload command les resemble INSERT statements in SQL, except that they cannot incorporate SELECT statements (since the data are not yet in any table). In effect, the most recent FILE statement replaces SELECT in dening the list of data values for a dbload INSERT statement to

enter as new rows.

E-12

INFORMIX-4GL Utility Programs

The dbload Utility

The format of a command le for dbload is indicated here:

FILE { "lename" } { DELIMITER "c" nelds | (eldn1 start [ - end ] [: . . . ] [ NULL = "null-str1" ] , eldn2 start [ - end ] [: . . . ] [ NULL = "null-str2" ] , . . . eldnN start [ - end ] [: . . . ] [ NULL = "null-strN" ] ) } ; INSERT INTO tablename [ (column-list) ] [ VALUES (value-list) ] ; [ . . . ]

The command le can include multiple FILE and INSERT statements. An explanation of these terms, notes, and an example follow.

Explanation
FILE

is a required keyword. is the pathname of an input le, enclosed between a pair of quotation ( " ) marks. is a keyword that is required if lename has variable-length data records. is the eld delimiter (enclosed in quotes) between elds of a variable-length data record, and before the NEWLINE character that terminates each record. is an integer, specifying the number of elds in each variable-length data record. is a name that you assign to a data eld within a xed-length record of lename. is an integer, indicating a character position within a xedlength record. is a hyphen ( - ) and an integer, indicating (with start) a range of character positions. is a keyword to specify a NULL symbol. is a quoted string, specifying a data value for which dbload should substitute a NULL. are required keywords. identies a table in which to store the data.

lename
DELIMITER

nelds eldn start -end

NULL

null-str
INSERT INTO

tablename

INFORMIX-4GL Utility Programs

E-13

The dbload Utility

column-list
VALUES

is a list of column names within tablename, separated by commas. is an optional keyword to specify a list that can include constants and data eld names. is a comma-separated list of constants and/or data eld names from lename.

value-list

Notes
1. The dbload utility recognizes valid owner.table references. 2. You need UNIX read permission for lename, and you must also be granted the INSERT privilege for tablename. 3. Every statement must end with a semicolon ( ; ) symbol. 4. You cannot specify character positions or null-str symbols in a record dened with the DELIMITER option. 5. Use a colon ( : ) to separate character position or range values in each data eld denition. The list of eld denitions must be enclosed in parentheses and separated by commas. 6. The same character position can be repeated in the FILE specication of a eld, or in different elds. (See the command le example that follows these notes.) 7. The scope of reference of a null-str is the eld for which you dene it, but you can dene the same null-str for other elds. 8. The DELIMITER option automatically assigns the sequential names f01, f02, f03, . . . to elds in variable-length records. The value-list of an INSERT statement can reference eld names assigned by the user or by dbload in the previous FILE statement. 9. If your INSERT statement omits the column-list, then the default columns are every column in tablename. If you do not specify a value-list, then the default values are those in every eld of the previous FILE statement. 10. An error results if the column-list and the value-list have different numbers of elements. 11. If the column-list includes fewer columns than tablename, dbload attempts to insert NULL values in the remaining columns. If a NOT NULL restriction or UNIQUE CONSTRAINT would be violated, the insertion fails, and an error message appears. 12. Inserted data types correspond to the explicit or default column-list. If the data eld width is different from its corresponding character column,
E-14 INFORMIX-4GL Utility Programs

The dbload Utility

inserted values are padded with blanks if the column is wider, or are truncated if the eld is wider. 13. Enclose between braces ( { } ) any comments in lename. 14. Use the DELIMITER option to avoid truncation of long character elds. If the delimiter c (or a backslash) appears as a literal character, you must prex it with a backslash ( \ ) in the input le. 15. If you specify DELIMITER, the same delimiter must be used throughout the input le and must appear in quotes in the FILE statement. You must remember to place the delimiter immediately before the NEWLINE character that marks the end of each record. (If you omit this delimiter, an error results whenever the last eld of a record is empty.)

Examples
FILE "datafile1" (fld1 1 - 10 : 13 : 5 - 22 NULL = "str1" , fld2 10 - 21 : 28 - 32 , fld3 8 - 10 : 33 - 50 : 29 - 33 NULL = "str2" , . . . fldN 9 : 16 - 19 NULL = "string") ;

INSERT INTO tab1 (col1, col2, col9, . . . , colN) ; INSERT INTO tab2 VALUES (fld1, fld3, "kevin", . . . , fldN) ; INSERT INTO tab3 ; {no column or values list provided} {variable-length fields}

FILE "datafile.2" DELIMITER "|" 8 ;

INSERT INTO tab1 VALUES (f01, f02, "kevin", "234", . . . , f08) ; INSERT INTO tab4 ;

Note: The ellipses (. . .) in this example are typographic conventions that cannot appear in command les. Unless you use the DELIMITER option, for example, you must explicitly list every eld that a FILE statement denes. Each statement in this example is described in the pages that follow.
FILE "datafile1" (fld1 1 - 10 : 13 : 5 - 22 NULL = "str1" ,

Here datale1 is the input le, and d1, d2, d3, through dN are userassigned eld names in its xed-length data records. In this example, d1 consists of the characters in positions 1 through 10, 13, and 5 through 22 of every datale1 record. (Each record ends with a NEWLINE character.) Notice that the characters 5 through 10 and 13 appear twice in d1, and characters 10, 13, and 21 appear in d1 and d2. In eld d1, the NULL symbol is dened as str1. A NULL value is entered whenever str1 is read in d1.
INFORMIX-4GL Utility Programs E-15

The dbload Utility

The d2 eld consists of positions 10 through 21, and 28 through 32. The d3 eld is dened as the characters in positions 8 through 10, 33 through 50, and 29 through 33. The NULL symbol for eld d3 is dened as str2. The eld-denition process continues until the last eld is reached. Field dN contains characters in positions 9, and 16 through 19. The NULL value is dened as string.
INSERT INTO tab1 (col1, col2, col9, . . . , colN) ;

An INSERT statement follows. Here col1, col2, col9, and so on are the actual database column names in table tab1. Since no value list is provided, dbload takes the values in the elds dened in the preceding FILE statement. It inserts the data from d1 into col1, from d2 into col2, from d3 into col9, and so forth, until the value from dN is inserted into colN. (Columns 4 through 8 are skipped, so the new rows will have NULL values there, if the columns permit NULLs.)
INSERT INTO tab2 VALUES (fld1, fld3, "kevin", . . . , fldN) ;

Since no column list is provided, dbload reads the names of all the columns in tab2 from the system catalogs. Values to load into each column are specied by eld names from the previous FILE statement or as constants. Data in d1 go into the rst column, data from d3 into the second, and the constant kevin into the third. The dbload utility continues until the value in dN is inserted into the nal column.
INSERT INTO tab3 ; {no column or values list provided}

As noted in the comment, this statement species no column names or data values. To create a default column-list, dbload checks the system catalogs for the names of all the columns in table tab3. The default value-list comes from the most recent FILE statement, in this case the rst statement in the command le. Data from d1 go into the rst column, data from d2 into the second, and so forth, with data from eld dN going into the Nth column. Note: This statement requires that the eld list in the FILE statement have a one-toone correspondence with the columns of table tab3, as listed in the system catalogs. Unless this correspondence exists, dbload will not load the records. Instead, you will receive an error message on each record. The loading process terminates when the total number of records that cannot be inserted as new rows exceeds a limit that you can specify at the dbload command line (by using the -c option).
FILE "datafile.2" DELIMITER "|" 8 ; {variable-length fields}

E-16

INFORMIX-4GL Utility Programs

The dbload Utility

The DELIMITER clause tells dbload that le datale.2 has variable-length elds, and that the vertical-bar character ( | = ASCII 124) separates each eld. Here 8 is the number of elds in each input record. Fields are automatically assigned the names f01, f02, f03, and so on.
INSERT INTO tab1 VALUES (f01, f02, "kevin", "234", . . . , f08) ;

A value-list but no column-list is specied, so dbload reads all the column names of tab1 from the system catalogs. Here the value in eld f01 goes into the rst column, the f02 value into the second, the constant kevin into the third, the constant 234 into the fourth, and so forth, until the value in eld f08 is inserted into the last column. You must reference elds in a variable-length data le with the letter f followed by a two-digit number: f01, f02, f10, and so on. Other formats like fld01 or f3 are incorrect.
INSERT INTO tab4 ;

Since no column-list or value-list is provided, dbload nds all the names of columns in table tab4 in the system catalogs. The value-list is all the elds dened in the previous FILE statement. (Notice that this is not the same FILE statement that was used with table tab3.) If these values have a one-to-one correspondence with the columns, the value from eld f01 goes into the rst column, the value from f02 into the second column, and so on, until the value in f08 is placed in the last column. An error results if 8 is not the number of columns in table tab4.

Specifying a dbload Command Line

After you have created a valid command le, you invoke dbload at the operating system prompt. The argument list that you include in your command line determines whether the program operates in command mode or interactive mode. If you enter the keyword dbload without any arguments, the screen displays a syntax summary for dbload usage, and control returns to the operating system.

INFORMIX-4GL Utility Programs

E-17

The dbload Utility

To use dbload to read and execute a command le, you must enter a command line that includes at least one of its required specications. The following elements are required in a dbload command line:
dbload { -d database | -c comle | -l logle } . . .

dbload -d database -c comle -l logle

invokes the dbload utility. identies a database to receive the new data. identies a dbload command le. identies a le to log any error messages.

The following sections describe both the interactive and command modes of dbload.

Running dbload Interactively

If you specify part (but not all) of the required information after the dbload keyword, the program automatically enters interactive mode and prompts you for additional specications. Depending on what you entered at the command line, these specications can include

The name of the database to receive the new data. The name of the command le to be executed. The name of an error log le in which to store any input le records that
dbload cannot insert into the database, as well as diagnostic information.

Whether you only want dbload to check the syntax of the FILE and
INSERT statements in your command le, without changing the database.

How many bad input records can be encountered before dbload stops
inserting new rows.

How many input le records to read before committing new rows to the
database, if your database supports transactions.

Whether to discard or to commit to the database any rows that were successfully read between the last COMMIT and the rst bad record that exceeds your cumulative error limit.

How many input records to ignore before dbload begins to insert data.
(That is, how many NEWLINE characters to read before actual processing begins.) After you enter these specications or press RETURN to accept the default values that appear in the prompts, the screen is cleared, and the dbload utility begins execution.

E-18

INFORMIX-4GL Utility Programs

The dbload Utility

Running dbload in Command Mode

If a valid dbload command line includes the required database, command le, and error log specications, with or without any additional options, program execution begins. The complete syntax of dbload is indicated here:

Syntax
dbload -d database -c comle -l logle [ -e num1 ] [ -n num2 ] [ -i num3 ] [ -p ] [ -r ] [ -s [ > outle ] ]

Explanation
dbload -d database -c comle -l logle -e num1 -n num2 -i num3 -p -r -s > outle is a required keyword. is the name of a database to receive the data. is the pathname of a dbload command le. is the pathname of an error logging le. is the number of bad records that dbload will read before it terminates (where num1 is an integer). displays a message after each batch of num2 new rows are inserted (where num2 is an integer). ignores the rst num3 input records (where num3 is an integer). prompts for instructions if the number of bad records exceeds num1. instructs dbload not to lock the table(s). (Otherwise, tablelevel locking occurs during loading.) instructs dbload only to check the syntax of the statements in comle, without inserting any data. is an optional > symbol and the name of a le in which to save output from the syntax check.

Notes
1. Unless you include at least one of the rst three options, dbload displays a help message and terminates. If you omit one or two of the three required options, dbload prompts you for additional specications. 2. You can prex comle, logle, or outle with a pathname.

INFORMIX-4GL Utility Programs

E-19

The dbload Utility

3. You should run dbload with the -s or -s > outle options before you begin loading data. These options perform a syntax check on the FILE and INSERT statements in comle and ignore any other options except -d database and -c comle. The screen displays comle with any errors marked where they are found. 4. If you do not specify a value for num1, the default is 10 bad records, so the program stops loading when it reads the 11th bad record. If you set num1 at zero, dbload terminates when it reads the rst bad record. 5. If your database supports transactions, dbload reads and inserts a batch of num2 records between each COMMIT. If you do not specify a value for num2, the default is 100 records. 6. The -i option instructs dbload to ignore the rst num3 lines in the input le, so processing does not begin until dbload has read num3 NEWLINE characters. This option is useful, for example, if your most recent dbload session with the same command le ended after 240 lines of input. You can resume loading at line 241 by setting num3 equal to 240. It is also useful if header information in the input le precedes the data records. 7. After (num1 + 1) bad records in a database with transactions, the -p option prompts you to roll back or to commit any rows inserted since the last transaction. The default is to commit. 8. If you press the Interrupt key, dbload terminates and discards any new rows that have been inserted but not yet committed to the database (if the database has transactions). 9. The presence of indexes greatly affects the speed with which the dbload utility loads data. For best performance, drop any indexes on the tables receiving the data before you run dbload. You can create new indexes after dbload has nished.

Examples
The following example shows a dbload command line at the system prompt that uses all options (except the -s option): dbload -d stores -c cfyl -l lfyl -e 5 -n 75 -i 20 -p -r This example species the following parameters: -d stores -c cfyl -l lfyl is the name of the database to receive the data. is the name of the dbload command le. is the name of the error-log le.

E-20

INFORMIX-4GL Utility Programs

The dbload Utility

-e 5 -n 75

species that dbload will log up to ve bad records. The program terminates if a 6th bad record is encountered. species that screen messages will indicate when successive batches of 75 rows have been inserted (or committed, in a database with transactions). tells dbload to ignore the rst 20 lines of the data le. Processing begins at the 21st line. prompts you to commit or discard any uncommitted rows after six bad records. tells dbload not to lock the table(s) of the stores database that are being accessed by dbload while the new rows are being inserted. This allows other users to access the same table(s) during the dbload operation. Unless you specify the -r option, table-level locking occurs.

-i 20 -p -r

Notice that the names of the input le and the table(s) to receive the data do not appear explicitly in the command line. These names must be specied within the dbload command le, which is called cfyl in this example.

INFORMIX-4GL Utility Programs

E-21

The dbschema Utility

The dbschema Utility

You can use the dbschema utility to produce quickly an SQL command le containing the CREATE TABLE, CREATE INDEX, and CREATE VIEW statements required to replicate an entire database or a selected table. In addition, dbschema can produce all CREATE SYNONYM and GRANT statements in effect for the database or a selected table or view. You must be the DBA or have CONNECT or RESOURCE permission to the database before you can run dbschema. By default, dbschema produces all CREATE TABLE, CREATE VIEW, CREATE INDEX, CREATE SYNONYM, and GRANT statements in effect for the entire database. By including the appropriate command-line option, you can limit the output to a selected table or view, or produce synonyms and permissions for a particular user. dbschema uses the owner.object convention when it generates any CREATE TABLE, CREATE INDEX, CREATE SYNONYM, CREATE VIEW, or GRANT statements, and when it reproduces any UNIQUE CONSTRAINTs. As a result, if you use the dbschema output to create a new object (table, index, view, or synonym), the new object is owned by the owner of the original object. If you want to change the owner of the new object, you must edit the dbschema output before running it as an SQL script. The syntax for the dbschema utility follows:
dbschema [-t tabname] [-s sname] [-p pname] -d database [lename]

-t tabname

species the table or view for which you want dbschema to output CREATE TABLE and CREATE INDEX statements or the CREATE VIEW statement. If you specify all for tabname, dbschema outputs the SQL statements for all database tables and views. species the user for whom you want dbschema to output the CREATE SYNONYM statements. If you specify all for sname, dbschema outputs all CREATE SYNONYM statements. If you include the -t option, dbschema produces the CREATE SYNONYM statements only for the indicated tabname. species the user for whom you want dbschema to output permission statements. If you specify all for pname, dbschema outputs the GRANT statements for all users. If you include the -t option, dbschema produces the GRANT statements only for the indicated tabname. species the name of the database.

-s sname

-p pname

-d database
E-22

INFORMIX-4GL Utility Programs

The dbschema Utility

lename

species the name of the le in which to save the dbschema output. If lename is not provided, dbschema outputs to the screen.

Notes
1. The following command line produces the SQL statements necessary to replicate an entire database:
dbschema -d database

where database is the name of the database. 2. You must be the DBA or have CONNECT or RESOURCE permission to the database before you can run dbschema on it. 3. When you include the -t option, dbschema produces SQL statements only for the indicated tabname. The dbschema utility uses the tabname to lter the output. If you use the -t option with the -p and -s options, only the CREATE SYNONYM and GRANT statements for tabname are provided. 4. All objects listed in the dbschema output include the name of the owner. If you want to use the dbschema output to create a schema with different owners, you must rst change the owner names in the output le. 5. All SERIAL elds included in CREATE TABLE statements output by dbschema have a starting value of one, regardless of their original starting value. 6. In the dbschema output, the AS keyword is used to indicate the grantor of a GRANT statement, as in the following example:
GRANT ALL ON "tom".customer TO "claire" AS "norma"

This statement tells you that norma issued the GRANT statement. 7. When the GRANT..AS keywords appear in your dbschema output, you may need to grant certain permissions before running the output as an SQL script. Consider the following GRANT statement:
GRANT tab-privilege ON user1.tablename TO "user2" AS "user3"

Before this statement can be run to create another schema, the following must be true:

user3 must have CONNECT permission to the database. user3 must have tab-privilege WITH GRANT OPTION for tablename.
8. The database must exist in your current directory or a directory cited in your DBPATH environment variable.

INFORMIX-4GL Utility Programs

E-23

The dbschema Utility

Examples
The following statement outputs the SQL statements relating to the customer table in the stores database to the le c_schema.sql.
dbschema -t customer -s alice -p dinah -d stores c_schema.sql

The output consists of the following components:

The CREATE TABLE and CREATE INDEX statements for the customer table All CREATE SYNONYM statements executed by the user alice on the
customer table

All permissions granted to the user dinah on the customer table

The output from this dbschema statement follows:
{ TABLE "alice".customer row size = 134 number of columns = 10 index size = 0 } CREATE TABLE "alice".customer ( customer_num serial not null, fname char(15), lname char(15), company char(20), address1 char(20), address2 char(20), city char(15), state char(2), zipcode char(5), phone char(18) ); REVOKE ALL ON "alice".customer FROM "public"; CREATE UNIQUE INDEX "alice".c_num_ix ON "alice".customer (customer_num); CREATE INDEX "alice".zip_ix ON "alice".customer (zipcode); GRANT ALL ON "alice".customer TO "dinah" AS "alice"; CREATE SYNONYM "alice".cust FOR "alice".customer;

The next dbschema statement outputs the SQL statements for all tables in the stores database to the le s_schema.sql.
dbschema -t all -s alice -p alice -d stores s_schema.sql

The output consists of the following components:

The CREATE TABLE, CREATE VIEW, and CREATE INDEX statements that
replicate all tables, views, and indexes in the stores database

All CREATE SYNONYM statements executed by the user alice All permissions granted to the user alice

E-24

INFORMIX-4GL Utility Programs

The dbupdate Utility

The dbupdate Utility

Databases created through Informix products that used an early implementation of SQL (Version 1.1 or earlier) have a different structure than databases created through products using the current implementation. The current structure includes additional system catalogs, content changes to some existing system catalogs (see Appendix B), and the introduction of NULL values. A database will have the old structure if it was created by an application using Version 2.0 (or earlier) of INFORMIX-ESQL/C, INFORMIX-ESQL/ COBOL, or INFORMIX-SQL or Version 1.0 of INFORMIX-4GL. Such a database cannot be used with current application development tools or database engines until the database is converted to the current structure. You can convert old databases to the current structure through the dbupdate utility.

Using dbupdate
To convert an old database to the new structure, execute the following command:
dbupdate [ -b | -n ] old-database-name new-database-name

The dbupdate utility creates a new database in the current directory with the name new-database-name, and copies the data from the old system catalogs to the new system catalogs, making the appropriate changes. If you do not use the -b or -n option, dbupdate converts the value of all CHAR type columns with blank data to NULL and, for each number column, asks you whether it should convert zero values to NULL values. The -b option causes dbupdate to leave blank data in CHAR columns as blanks. The -n option alters the system catalogs to dene all columns as NOT NULL, and does not touch the data les. The -n option includes the -b option. In addition to these changes, dbupdate corrects a bug in the representation of negative DECIMAL values. When dbupdate nishes, you have two database directories (the new and the old) with two separate system catalogs, but the data and index les are shared (linked). To complete the update, you should remove the old database directory.

INFORMIX-4GL Utility Programs

E-25

The dbupdate Utility

No NULL Databases
You may want to avoid dealing with NULL values and their three-valued logic. You can do this if you carefully adhere to the following rules:

When converting an old database, select the -n option of dbupdate. When creating new tables, dene all columns as NOT NULL. In all form specication les, add the WITHOUT NULL INPUT clause in the
DATABASE section.

In form specication les, specify all formonly elds as NOT NULL.

The last two rules mean that you must recompile all your old form specication les.

E-26

INFORMIX-4GL Utility Programs

The mkmessage Utility

The mkmessage Utility

The mkmessage utility converts ASCII source les that contain user messages into a format that 4GL programs can use in on-line displays. This section describes how to use mkmessage with help les and with customized runtime error messages.

Programmer-Dened Help Messages

When executing an INFORMIX-4GL program, the user can request help whenever the program is waiting for user input. This can occur while making a menu selection, while inputting data to a form, or while responding to a prompt. You can supply help messages that are displayed whenever the user presses the Help key (specied in the OPTIONS statement). These messages can be specic to the menu option currently highlighted, or to the INPUT, INPUT ARRAY, or PROMPT statement.

Message Source Files

INFORMIX-4GL looks for the appropriate help message in the help le that you specify in an OPTIONS statement, using the HELP FILE option. You can have several help les, but only one can be in effect at a time. The structure of the message source le is very simple:

Syntax
.num message-text ... [ ... ]

Explanation
.num message-text is a period, followed by an integer. is a line of characters and/or blanks.

Notes
1. Each line must end in a RETURN. 2. Each help message should be preceded by a line with nothing on it but a period (in the rst column) and a unique integer num.
INFORMIX-4GL Utility Programs E-27

The mkmessage Utility

3. The message-text starts on the next line, and continues until the next numbered line. 4. You can use the integer num to identify the help message in your INFORMIX-4GL programs. (See the INPUT, INPUT ARRAY, MENU, and PROMPT statement descriptions in Chapter 7.) 5. All blank lines between two numbered lines are considered part of the message that belongs to the rst of the two numbers. 6. Lines beginning with # are considered comment lines, and are ignored by mkmessage. 7. If the text of a message occupies more than 20 lines, INFORMIX-4GL automatically breaks the message into pages of 20 lines. You can change these default page breaks by entering CTRL-L in the rst column of a line in your message le to start a new page. 8. INFORMIX-4GL handles clearing and redisplaying the screen.

Examples
For an example, see the helpdemo.src le from the demonstration application in Appendix A. (See also the section Creating a Help File in Chapter 8 of the INFORMIX-4GL User Guide.)

Creating Executable Message Files

Once you have created your message source le, you can process it for use by INFORMIX-4GL with this syntax:

Syntax
mkmessage helple.src helple.out

Explanation
helple.src helple.out is an ASCII source le of help messages. is the pathname of the executable output le.

E-28

INFORMIX-4GL Utility Programs

The mkmessage Utility

Notes
1. You can give the input and output help les any valid names and extensions in place of those shown above. 2. You can specify the output help le name in the OPTIONS statement to identify it as the current help le. 3. If you want to use help messages from the help le on a eld-by-eld basis in an INPUT or INPUT ARRAY statement, you must use the ineld() and showhelp( ) library functions that are supplied with INFORMIX-4GL.

Examples
The example that follows illustrates the use of these functions:
OPTIONS HELP FILE "stores.hlp", HELP KEY F1 ... INPUT pr_fname, pr_lname, pr_phone FROM fname, lname, phone HELP 101 ON KEY (F1) CASE WHEN INFIELD(lname) CALL showhelp(111) WHEN INFIELD(fname) CALL showhelp(112) WHEN INFIELD(phone) CALL showhelp(113) OTHERWISE CALL showhelp(101) END CASE END INPUT

Customized Error Messages

You can also use the mkmessage utility to customize run-time error messages. INFORMIX-4GL is distributed with a le called 4glusr.msg. This ASCII le contains some common error messages (as listed later in this volume), including the messages for run-time errors that cannot be trapped by the WHENEVER ERROR statement, and messages that support the 4GL Help menu. The 4glusr.iem le contains the executable version of this le. You can edit the messages in 4glusr.msg with a text editor (for example, to make them specic to a 4GL application, or to translate them into another language). Be sure to preserve the required numeric codes, prexed by a period ( . ) to identify each message.
INFORMIX-4GL Utility Programs E-29

The mkmessage Utility

If you choose to modify the contents of the 4glusr.msg message le, you must specify 4glusr.iem in your mkmessage command line as the object le name: mkmessage source-le-name 4glusr.iem The executable le 4glusr.iem is initially installed in the directory $INFORMIX/msg. INFORMIX-4GL looks for message les in one of two directories, namely /$INFORMIXDIR/$DBLANG or else /$INFORMIXDIR/msg. If $DBLANG is dened, 4GL looks only in /$INFORMIXDIR/$DBLANG. If this is not dened, 4GL looks only in /$INFORMIXDIR/msg. You must place the newly modied le 4glusr.iem in the appropriate /$INFORMIXDIR/msg or /$INFORMIXDIR/$DBLANG directory.

E-30

INFORMIX-4GL Utility Programs

The sqlconv Utility

The sqlconv Utility

The sqlconv utility is provided for the Database Administrator who wants to use INFORMIX-SQL, INFORMIX-ESQL/C, or INFORMIX-4GL with a database that was created with the non-SQL product INFORMIX (Version 3.2 or 3.3). From the INFORMIX database, sqlconv aids a user in creating a new SQLcompatible database. It leaves the old database intact. This appendix discusses the steps necessary to convert an INFORMIX database to an SQL-compatible database. The new database can be used with INFORMIX-SQL, INFORMIX-ESQL/C, or INFORMIX-4GL. If you have purchased INFORMIX-SQL or INFORMIX-ESQL/C in addition to INFORMIX-4GL, and you have already run the sqlconv utility provided with the other product, you do not need to run sqlconv again. This appendix describes two methods you can use to accomplish a database conversion. The method you should use depends on the disk space constraints of your system. Caution: sqlconv will not convert INFORMIX database permissions. You must grant new permissions on tables and elds after your new 4GL database has been created and loaded.
INFORMIX-4GL reserved words are not the same as INFORMIX reserved words. If you receive a syntax error while running your new 4GL programs, make sure that

your table and eld names are not among the new reserved words. For a list of reserved words, see Appendix D in this manual. Make sure all INFORMIX composite elds are indexed. Indexed composite elds will have composite indexes created for them. If you have used the LOCATION option to spread an INFORMIX database across a number of directories, converting the database using sqlconv places all of these les in the new .dbs directory. You cannot specify a new starting number for a SERIAL column.

INFORMIX-4GL Utility Programs

E-31

The sqlconv Utility

Conversion Procedures
If There Is No Shortage of Disk Space
You can convert an entire INFORMIX database to an SQL compatible database for use with INFORMIX-4GL at one time if there is no shortage of disk space. To convert an entire database at once, you must have available on the disk at least three times the amount of space required by all the tables in the database plus additional space for the 4GL system les. The following steps outline the process of converting an entire database at once: 1. Make certain that INFORMIX and INFORMIX-4GL are included in your search path. 2. Set the INFORMIXDIR environment variable to point to the INFORMIX-4GL directory. 3. Change your current directory to the directory that contains your INFORMIX database. 4. Create a backup copy of the INFORMIX database. 5. Enter
sqlconv -e databasename

where databasename is the name of the INFORMIX database that you want to convert. Do not include a lename extension. This command generates an INFORMER script le (indicated by a .uld extension), an INFORMIX-4GL program (indicated by a .4gl extension), and a dbload command le (indicated by a .cmd extension). 6. Enter
informer databasename databasename.uld

This command unloads the database les (in ASCII format) to unload les (indicated by a .unl extension) for each table in the database.

E-32

INFORMIX-4GL Utility Programs

The sqlconv Utility

7. If you have the C Compiler Version of INFORMIX-4GL, enter

c4gl databasename.4gl -o databasename.out

This command compiles the 4GL program created in Step 5, and creates an executable le with extension .out. If you have the RDS version of INFORMIX-4GL, enter
fglpc databasename.4gl

This creates a p-code le databasename.4go from the 4GL program that you created in Step 5. 8. If you have the C Compiler Version of INFORMIX-4GL, enter
databasename.out

This command runs the INFORMIX-4GL program that you compiled in Step 7 and re-creates the database, tables, and indexes in SQL format. If you have the RDS version of INFORMIX-4GL, enter
fglgo databasename.4go

This executes the p-code le that you created in Step 6, and re-creates the database, tables, and indexes in SQL format, but it does not load the data. 9. Enter
dbload -d databasename -c databasename.cmd -l errlog

This command loads the data from the .unl les (generated by informer) into the appropriate tables, and creates an errlog le, which contains diagnostic information about any rows that were not successfully loaded. For more information on dbload, see The dbload Utility in this appendix. 10. The nal step in the conversion procedure is to remove all the old database les, and the .uld, .4gl, .cmd, .unl, .out or .4go les from your directory, and any .ec or .c les that may have been created if you have the C Compiler Version of INFORMIX-4GL. Do not remove your forms and reports. You can update these later.

If There Is a Shortage of Disk Space

The following method is more economical in terms of disk space, but it is a more involved and time-consuming process than the method discussed in the previous section. Use this method if you do not have at least three times the amount of space required by the database.

INFORMIX-4GL Utility Programs

E-33

The sqlconv Utility

The following steps outline the conversion of the example INFORMIX database, payroll, to an SQL-compatible database for use with 4GL: 1. Make certain that INFORMIX and INFORMIX-4GL are included in your search path. 2. Set the INFORMIXDIR environment variable to point to the INFORMIX-4GL directory. 3. Change your current directory to the directory that contains your INFORMIX database. 4. Create a backup copy of the INFORMIX database. 5. Enter
sqlconv -e payroll

Do not include a lename extension. This command generates an INFORMER script le (indicated by a .uld extension), an 4GL program (indicated by a .4gl extension), and a dbload command le (indicated by a .cmd extension). 6. If you have the C Compiler Version of INFORMIX-4GL, enter
c4gl payroll.4gl -o payroll.out

This command compiles the 4GL program that you created in Step 5, and creates an .out executable le. If you have the RDS version of INFORMIX-4GL, enter
fglpc payroll.4gl

This creates a p-code le payroll.4go from the 4GL program that you created in Step 5. 7. If you have the C Compiler Version of INFORMIX-4GL, enter
payroll.out

This command runs the INFORMIX-4GL program you compiled in Step 6, and re-creates the database, tables, and indexes in SQL format, but it does not load the data. If you have the RDS version of INFORMIX-4GL, enter
fglgo payroll.4go

This executes the p-code le that you created in Step 6, and re-creates the database, tables, and indexes in SQL format, but it does not load the data.

E-34

INFORMIX-4GL Utility Programs

The sqlconv Utility

8. Enter
cat payroll.uld

The statements in the payroll.uld le outline the rst steps of the conversion operation. You must execute each of these statements separately. You may nd it helpful to print a copy of the payroll.uld le for easy reference. 9. Enter
informer payroll

At the INFORMER prompt, enter the rst line of the payroll.uld le exactly as it appears. This creates the unload le for the rst table. Exit from INFORMER. 10. The .cmd le describes the form of the data and contains the INSERT INTO statements indicating how this data is to be placed in the database les. The INSERT INTO statements are necessary to load the data into the newly created database. You must execute each of the statements separately. To do this, create a copy of the payroll.cmd le for each INSERT INTO statement and make sure you include the .cmd extension to the lename of each new le. In this instance, we have named the les one.cmd and two.cmd. 11. Edit the one.cmd le using your system editor, and remove all but the rst INSERT INTO statement from the le. Exit from the le. 12. Execute the rst INSERT INTO statement in the one.cmd le by entering
dbload -d payroll -c one.cmd -l errlog

This command loads the data from the .unl le into the appropriate table and creates an errlog le, which contains diagnostic information about any rows that were not successfully loaded. A statement appears on the screen indicating how many rows were loaded into the le. For more information on dbload, see The dbload Utility in this manual. 13. Before you can perform the same operations on any other database tables, you must free additional disk space by erasing the INFORMIX versions of the recently created INFORMIX-4GL les. To erase these les, enter
dbstatus payroll

14. At the dbstatus prompt, enter

erase file filename

where lename is the name of the le referred to in the .cmd le created in Step 11. Exit from dbstatus.
INFORMIX-4GL Utility Programs E-35

The sqlconv Utility

15. Erase the unload le for this same le by entering from the command line
rm filename.unl

16. Continue to unload each table, one at a time, from the INFORMIX database and then load it into the INFORMIX-4GL database. Do this by repeating Steps 9 through 15. Remember to make a copy of the .cmd le for each INSERT INTO statement it contains. Each copy must have a unique name and must end in the .cmd extension. The correct lename must be included on the command line each time you run the dbload command. Repeat these steps until all load statements in the payroll.cmd le have been executed. This operation loads the actual data into the newly created database. 17. Check the contents of the data les in the newly created database to make sure you have successfully converted your INFORMIX database. 18. When all tables in the database have been converted, erase the .uld, .4gl, .cmd, .out, or .4go les from your directory (and any .ce or .c les that may have been created if you have the C Compiler Version of INFORMIX-4GL) and drop the INFORMIX database. Caution: You cannot rerun sqlconv after you have erased a table. The new scripts generated by the command do not contain the information necessary to convert the table.

E-36

INFORMIX-4GL Utility Programs

The upscol Utility

The upscol Utility

The upscol utility program allows you to create and modify the syscolval and syscolatt tables, which contain default information for elds in screen forms that correspond to database columns. Chapter 4 describes these tables and their use by INFORMIX-4GL. You invoke the upscol utility by entering the command upscol in response to the system prompt. After you select a database (db-name) at the CHOOSE DATABASE screen, the following menu appears:
UPDATE SYSCOL: Validate Attributes Exit Update information in the data validation table. -------------------- db-name ------------------- Press CTRL-W for Help --------

The options in the UPDATE SYSCOL Menu are Validate Attributes Exit Update the information in syscolval. Update the information in syscolatt. Return to the operating system.

If you select either Validate or Attributes, upscol checks whether the corresponding table exists and, if not, asks whether you want to create it. In the text that follows, the corresponding table is called syscol. If you choose not to create it, enter n, and you will return to the UPDATE SYSCOL Menu. If the data validation table already exists, or if you enter y to create it, upscol displays the CHOOSE TABLE screen, and prompts you for the name of a table (tab-name) in db-name. After you select a table, the CHOOSE COLUMN screen prompts you to select the name of a column (col-name) whose default values you want to modify in syscol.

INFORMIX-4GL Utility Programs

E-37

The upscol Utility

The selected table and column names appear, along with the database name, on the dividing line beneath the next menu, which is called the ACTION Menu:
ACTION: Add Update Remove Next Query Table Column Exit Add an entry to the data validation [or screen display attribute] table. --------- db-name:tab-name:col-name ------------ Press CTRL-W for Help --------

Now upscol displays the rst row of syscol that relates to tab-name and col-name in the work area beneath this menu. If no such entries exist, a message stating this appears on the Error line. The options in the ACTION Menu are Add Update Remove Next Query Table Column Exit Add new rows to the syscol table. Update the currently displayed row. Remove the currently displayed row (after a prompt for verication). Display the next row of syscol. Restart the display at the rst row of syscol for tab-name and col-name. Select a new database table and column. Select a new column within tab-name. Return to the UPDATE SYSCOL Menu.

E-38

INFORMIX-4GL Utility Programs

The upscol Utility

Adding or Updating Under the Validate Option

When you select Add in the ACTION Menu after choosing the Validate option in the UPDATE SYSCOL Menu, the VALIDATE Menu appears:
VALIDATE: Autonext Comment Default Include Picture Shift Verify Automatically proceed to next field when at end of current field. Exit

--------- db-name:tab-name:col-name ------------ Press CTRL-W for Help --------

The options are attribute names and their selection has the following effects: Autonext Comment Produces a menu with three options, Yes, No, and Exit. Exit returns you to the VALIDATE Menu. The default is No. Produces a prompt to enter a Comment line message. No quotation marks are required around the comment, but it must t on a single screen line. Produces a prompt to enter the DEFAULT attribute, formatted as described in Chapter 4. Quotation marks are required where necessary to avoid ambiguity. Produces a prompt to enter the INCLUDE attribute, formatted as described in Chapter 4. Quotation marks are required where necessary to avoid ambiguity. Produces a prompt to enter the PICTURE attribute, formatted as described in Chapter 4. No quotation marks are required. Produces a menu with four options, Up, Down, None, and Exit. Up corresponds to the UPSHIFT attribute and Down to the DOWNSHIFT attribute. Exit returns you to the VALIDATE Menu. The default is None. Produces a menu with three options, Yes, No, and Exit. Exit returns you to the VALIDATE Menu. The default is No. Returns you to the ACTION Menu.

Default

Include

Picture Shift

Verify Exit

The upscol utility adds or modies a row of syscolval after you complete each of these options except Exit.

INFORMIX-4GL Utility Programs

E-39

The upscol Utility

The Update option on the ACTION Menu takes you immediately to the ATTRIBUTE Menu or prompt corresponding to the current attribute for the current column. You can look at another attribute for the current column by using the Next option, start through the list again by using the Query option, remove the current attribute with the Remove option, and select a new column or table with the Column or Table options.

Adding or Updating Under the Attribute Option

When you select Add or Update in the ACTION Menu after choosing the Attribute option in the UPDATE SYSCOL Menu, the ATTRIBUTE Menu appears:
ATTRIBUTE: Blink Color Fmt Set Field blinking attribute Left Rev Under Where Discrd_Exit Exit_Set

--------- db-name:tab-name:col-name ------------ Press CTRL-W for Help --------

If you are adding a new row to syscolatt, a default row is displayed in the work area below the menu. If you are updating an existing row of syscolatt, the current row appears. Since no entry is made in syscolatt until you select Exit_Set, you can alter all the attributes before deciding to modify syscolatt (Exit_Set) or to abort the changes (Discrd_Exit). The options of the ATTRIBUTE Menu are screen attribute names, and their selection has the following effects: Blink Color Produces a menu with three options, Yes, No, and Exit. The default is No. Produces a menu with the available colors (color terminals) or intensities (monochrome terminals) for display of tabname.col-name. The colors displayed are those in the local colornames le, whose format is described in Appendix I. If no such le exists locally, upscol looks in $INFORMIXDIR/ incl. If the le does not exist there, upscol uses the default color list (see Chapter 4). You can toggle back and forth among the colors or intensities using CTRL-N.

E-40

INFORMIX-4GL Utility Programs

The upscol Utility

Fmt Left

Prompts you for the format string to be used when tabname.col-name is displayed. Produces a menu with three options, Yes, No, and Exit. Yes causes numeric data to be left justied within the screen eld. The default is No. Produces a menu with three options, Yes, No, and Exit. Yes causes the eld to be displayed in reverse video. The default is No. Produces a menu with three options, Yes, No, and Exit. Yes causes the eld to be displayed with underlining. The default is No. Prompts for the values and value ranges under which these attributes will apply. See Chapter 4 for allowable syntax. Discards the indicated changes and returns to the ACTION Menu. Enters the indicated changes into the syscolatt table and returns to the ACTION Menu.

Rev

Under

Where Discrd_Exit Exit_Set

After you complete each of these options except Discrd_Exit, upscol adds or modies a row of syscolatt. Note: Whoever runs the upscol utility produces a pair of tables, syscolval and syscolatt, that provide default values for all the users of a database that is not MODE ANSI. If the current database is MODE ANSI, however, the user who runs upscol becomes the owner of the syscolatt and syscolval tables specied at the upscol menus, but other users can produce their own user. syscolval and user.syscolatt tables. The default specications in an upscol table are applied by INFORMIX-4GL only to columns of database tables that have the same owner as the upscol table. (For details, see the section The upscol Tables in a MODE ANSI Database in Chapter 4, and the notes on the INITIALIZE and VALIDATE statements in Chapter 7.)

INFORMIX-4GL Utility Programs

E-41

The upscol Utility

E-42

INFORMIX-4GL Utility Programs

Appendix

DECIMAL Functions for C

The data type DECIMAL is a machine-independent method for the representation of numbers of up to thirty-two significant digits, with or without a decimal point, and exponents in the range -128 to +126. INFORMIX-4GL provides routines that facilitate the conversion of DECIMAL-type numbers to and from every data type allowed in the C language.
DECIMAL-type numbers consist of an exponent and a mantissa (or fractional part) in base 100. In normalized form, the rst digit of the mantissa must be greater than zero.

When used within a C program, DECIMAL-type numbers are stored in a C structure of the type shown below.
#define DECSIZE 16 struct decimal { short dec_exp; short dec_pos; short dec_ndgts; char dec_dgts[DECSIZE]; }; typedef struct decimal dec_t;

The decimal structure and the typedef dec_t shown above can be found in the header le decimal.h. Include this le in all C source les that use any of the decimal routines:
#include <decimal.h>

DECIMAL-Type Routines

The decimal structure has four parts: dec_exp dec_pos dec_ndgts dec_dgts holds the exponent of the normalized DECIMAL-type number. This exponent represents a power of 100. holds the sign of the DECIMAL-type number (1 when the number is zero or greater; 0 when less than zero). contains the number of base 100 signicant digits of the DECIMAL-type number. is a character array that holds the signicant digits of the normalized DECIMAL-type number (dec_dgts[0] != 0). Each character in the array is a one-byte binary number in base 100. dec_ndgts contains the number of signicant digits in dec_dgts.

DECIMAL-Type Routines
All operations on DECIMAL-type numbers should take place through the routines provided in the INFORMIX-4GL library and described in the following pages. Any other operations, modications, or analysis of DECIMAL-type numbers can produce unpredictable results. The following C function calls are available in INFORMIX-4GL to treat DECIMAL-type numbers:
deccvasc( ) dectoasc( ) deccvint( ) dectoint( ) deccvlong( ) dectolong( ) deccvflt( ) dectoflt( ) deccvdbl( ) dectodbl( ) decadd( ) decsub( ) decmul( ) decdiv( ) deccmp( ) deccopy( ) dececvt( ) decfcvt( ) convert C char type to DECIMAL-type convert DECIMAL-type to C char type convert C int type to DECIMAL-type convert DECIMAL-type to C int type convert C long type to DECIMAL-type convert DECIMAL-type to C long type convert C float type to DECIMAL-type convert DECIMAL-type to C float type convert C double type to DECIMAL-type convert DECIMAL-type to C double type add two decimal numbers subtract two decimal numbers multiply two decimal numbers divide two decimal numbers compare two decimal numbers copy a decimal number convert decimal value to ASCII string (corresponds to ecvt(3) on UNIX systems) convert decimal value to ASCII string (corresponds to fcvt(3) on UNIX systems)

F-2 DECIMAL Functions for C

DECCVASC

DECCVASC
Overview
Use deccvasc to convert a value held as a printable character in a C char type into a DECIMAL-type number.

Syntax
deccvasc(cp, len, np) char *cp; int len; dec_t *np;

Explanation
cp len np points to a string that holds the value to be converted. is the length of the string. is a pointer to a dec_t structure to receive the result of the conversion.

Notes
1. The deccvasc function ignores leading spaces in the character string. 2. The character string can have a leading plus (+) or minus (-) sign, a decimal point (.), and numbers to the right of the decimal point. 3. The character string can contain an exponent preceded by either e or E. The exponent can be preceded by a plus or minus sign.

Return Codes
0 -1200 -1201 -1213 -1216 Function was successful. Number is too large to t into a DECIMAL-type (overow). Number is too small to t into a DECIMAL-type (underow). String has non-numeric characters. String has bad exponent.

DECIMAL Functions for C F-3

DECCVASC

Examples
#include <decimal.h> char input[80]; dec_t number; . . . /* get input from terminal */ getline(input); /* convert input into decimal number */ deccvasc(input, 32, &number);

F-4 DECIMAL Functions for C

DECTOASC

DECTOASC
Overview
Use dectoasc to convert a DECIMAL-type number to an ASCII string.

Syntax
dectoasc(np, cp, len, right) dec_t *np; char *cp; int len; int right;

Explanation
np cp len right is a pointer to the decimal structure whose associated decimal value you want to convert to an ASCII string. is a pointer to the beginning of the character buffer to hold the ASCII string. is the maximum length in bytes of the string buffer. is an integer indicating the number of decimal places to the right of the decimal point.

Notes
1. If right equals -1, the number of decimal places is determined by the decimal value of *np. 2. If the number does not t into a character string of length len, dectoasc converts the number to exponential notation. If the number still does not t, dectoasc lls the string with asterisks. If the number is shorter than the string, it is left-justied and padded on the right with blanks. 3. Because the ASCII string returned by dectoasc is not null-terminated, your program must add a null character to the string before printing it.

Return Codes
0 -1 Conversion was successful. Conversion was not successful.
DECIMAL Functions for C F-5

DECTOASC

Examples
#include <decimal.h> char input[80]; char output[16]; dec_t number; . . . /* get input from terminal */ getline(input); /* convert input into decimal number */ deccvasc(input, 32, &number); /* convert number to ASCII string */ dectoasc(&number, output, 15, 1); /* add null character to end of string prior to printing */ output[15] = \0; /* print the value just entered */ printf("You just entered %s", output);

F-6 DECIMAL Functions for C

DECCVINT

DECCVINT
Overview
Use deccvint to convert a C type int into a DECIMAL-type number.

Syntax
deccvint(integer, np) int integer; dec_t *np;

Explanation
integer is the integer you want to convert. np is a pointer to a dec_t structure that receives the result of the conversion.

Examples
#include <decimal.h> dec_t decnum; /* convert the integer value -999 * into a DECIMAL-type number */ deccvint(-999, &decnum);

DECIMAL Functions for C F-7

DECTOINT

DECTOINT
Overview
Use dectoint to convert a DECIMAL-type number into a C type int.

Syntax
dectoint(np, ip) dec_t *np; int *ip;

Explanation
np ip is a pointer to a decimal structure whose value is converted to an integer. is a pointer to the integer.

Return Codes
0 -1200 Conversion was successful. The magnitude of the DECIMAL-type number > 32767.

Examples
#include <decimal.h> dec_t mydecimal; int myinteger; /* convert the value in * mydecimal into an integer * and place the results in * the variable myinteger. */ dectoint(&mydecimal, &myinteger);

F-8 DECIMAL Functions for C

DECCVLONG

DECCVLONG
Overview
Use deccvlong to convert a C type long value into a DECIMAL-type number.

Syntax
deccvlong(lng, np) long lng; dec_t *np;

Explanation
lng np is a pointer to a long integer. is a pointer to a dec_t structure that receives the result of the conversion.

Examples
#include <decimal.h> dec_t mydecimal; long mylong; /* Set the decimal structure * mydecimal to 37. */ deccvlong(37L, &mydecimal); mylong = 123456L; /* Convert the variable mylong into * a DECIMAL-type number held in * mydecimal. */ deccvlong(mylong, &mydecimal);

DECIMAL Functions for C F-9

DECTOLONG

DECTOLONG
Overview
Use dectolong to convert a DECIMAL-type number into a C type long.

Syntax
dectolong(np, lngp) dec_t *np; long *lngp;

Explanation
np lngp is a pointer to a decimal structure. is a pointer to a long where the result of the conversion will be placed.

Return Codes
0 -1200 Conversion was successful. The magnitude of the DECIMAL-type number > 2,147,483,647.

Examples
#include <decimal.h> dec_t mydecimal; long mylong; /* convert the DECIMAL-type value * held in the decimal structure * mydecimal to a long pointed to * by mylong. */ dectolong(&mydecimal, &mylong);

F-10 DECIMAL Functions for C

DECCVFLT

DECCVFLT
Overview
Use deccvt to convert a C type oat into a DECIMAL-type number.

Syntax
deccvflt(flt, np) float flt; dec_t *np;

Explanation
t np is a oating-point number. is a pointer to a dec_t structure that receives the result of the conversion.

Examples
#include <decimal.h> dec_t mydecimal; float myfloat; /* Set the decimal structure * myfloat to 3.14159. */ deccvflt(3.14159, &mydecimal); myfloat = 123456.78; /* Convert the variable myfloat into * a DECIMAL-type number held in * mydecimal. */ deccvflt(myfloat, &mydecimal);

DECIMAL Functions for C

F-11

DECTOFLT

DECTOFLT
Overview
Use dectot to convert a DECIMAL-type number into a C type oat.

Syntax
dectoflt(np, fltp) dec_t *np; float *fltp;

Explanation
np tp is a pointer to a decimal structure. is a pointer to a oating-point number to receive the result of the conversion.

Notes
The resulting oating-point number has eight signicant digits.

Examples
#include <decimal.h> dec_t mydecimal; float myfloat; /* convert the DECIMAL-type value * held in the decimal structure * mydecimal to a floating point number pointed to * by myfloat. */ dectoflt(&mydecimal, &myfloat);

F-12 DECIMAL Functions for C

DECCVDBL

DECCVDBL
Overview
Use deccvdbl to convert a C type double into a DECIMAL-type number.

Syntax
deccvdbl(dbl, np) double dbl; dec_t *np;

Explanation
dbl np is a double-precision, oating-point number. is a pointer to a dec_t structure that receives the result of the conversion.

Examples
#include <decimal.h> dec_t mydecimal; double mydouble; /* Set the decimal structure * mydecimal to 3.14159. */ deccvdbl(3.14159, &mydecimal); mydouble = 123456.78; /* Convert the variable mydouble into * a DECIMAL-type number held in * mydecimal. */ deccvdbl(mydouble, &mydecimal);

DECIMAL Functions for C

F-13

DECTODBL

DECTODBL
Overview
Use dectodbl to convert a DECIMAL-type number into a C type double.

Syntax
dectodbl(np, dblp) dec_t *np; double *dblp;

Explanation
np dblp is a pointer to a decimal structure. is a pointer to a double-precision, oating-point number that receives the result of the conversion.

Notes
The resulting double-precision number receives a total of 16 signicant digits.

Examples
#include <decimal.h> dec_t mydecimal; double mydouble; /* convert the DECIMAL-type value * held in the decimal structure * mydecimal to a double pointed to * by mydouble. */ dectodbl(&mydecimal, &mydouble);

F-14 DECIMAL Functions for C

DECADD, DECSUB, DECMUL, and DECDIV

DECADD, DECSUB, DECMUL, and DECDIV

Overview
The decimal arithmetic routines take pointers to three decimal structures as parameters. The rst two decimal structures hold the operands of the arithmetic function. The third decimal structure holds the result.

Syntax
decadd(n1, n2, result) dec_t *n1; dec_t *n2; dec_t *result; decsub(n1, n2, result) dec_t *n1; dec_t *n2; dec_t *result; decmul(n1, n2, result) dec_t *n1; dec_t *n2; dec_t *result; decdiv(n1, n2, result) dec_t *n1; dec_t *n2; dec_t *result; /* result = n1 + n2 */

/* result = n1 - n2 */

/* result = n1 * n2 */

/* result = n1 / n2 */

Explanation
n1 n2 result is a pointer to the decimal structure of the rst operand. is a pointer to the decimal structure of the second operand. is a pointer to the decimal structure of the result of the operation.

Notes
The result can use the same pointer as either n1 or n2.

DECIMAL Functions for C

F-15

DECADD, DECSUB, DECMUL, and DECDIV

Return Codes
0 -1200 -1201 -1202 Operation was successful. Operation resulted in overow. Operation resulted in underow. Operation attempts to divide by zero.

F-16 DECIMAL Functions for C

DECCMP

DECCMP
Overview
Use deccmp to compare two DECIMAL-type numbers.

Syntax
int deccmp(n1, n2) dec_t *n1; dec_t *n2;

Explanation
n1 n2 is a pointer to the decimal structure of the rst number. is a pointer to the decimal structure of the second number.

Return Codes
0 -1 +1 The two values are the same. The rst value is less than the second. The rst value is greater than the second.

DECIMAL Functions for C

F-17

DECCOPY

DECCOPY
Overview
Use deccopy to copy one dec_t structure to another.

Syntax
deccopy(n1, n2) dec_t *n1; dec_t *n2;

Explanation
n1 n2 is a pointer to the source dec_t structure. is a pointer to the destination dec_t structure.

F-18 DECIMAL Functions for C

DECECVT and DECFCVT

DECECVT and DECFCVT

Overview
These functions convert a DECIMAL value to an ASCII string.

Syntax
char *dececvt(np, ndigit, decpt, sign) dec_t *np; int ndigit; int *decpt; int *sign; char *decfcvt(np, ndigit, decpt, sign) dec_t *np; int ndigit; int *decpt; int *sign;

Explanation
np ndigit decpt is a pointer to a dec_t structure that contains the number you want to convert. is, for dececvt, the length of the ASCII string; for decfcvt, it is the number of digits to the right of the decimal point. points to an integer that is the position of the decimal point relative to the beginning of the string. A negative value for *decpt means to the left of the returned digits. is a pointer to the sign of the result. If the sign of the result is negative, *sign is nonzero; otherwise, the value is zero.

sign

Notes
1. The dececvt function converts the decimal value pointed to by np into a null-terminated string of ndigit ASCII digits, and returns a pointer to the string. 2. The low-order digit of the DECIMAL number is rounded. 3. The decfcvt function is identical to dececvt, except that ndigit species the number of digits to the right of the decimal point instead of the total number of digits.
DECIMAL Functions for C F-19

DECECVT and DECFCVT

Examples
In the following example, np points to a dec_t structure containing 12345.67 and *decpt points to an integer containing a 5:
ptr ptr ptr ptr = = = = dececvt dececvt decfcvt decfcvt (np,4,&decpt,&sign); (np,10,&decpt,&sign); (np,1,&decpt,&sign); (np,3,&decpt,&sign); = = = = 1235 1234567000 123457 12345670

In this example, np points to a dec_t structure containing a 0.001234 and *decpt points to an integer containing a -2:
ptr ptr ptr ptr = = = = dececvt dececvt decfcvt decfcvt (np,4,&decpt,&sign); (np,10,&decpt,&sign); (np,1,&decpt,&sign); (np,3,&decpt,&sign); = 1234 = 1234000000 = = 1

F-20 DECIMAL Functions for C

Appendix

Outer Joins
This appendix discusses the difference between a simple join and an outer join, and describes in detail how outer joins work. The following SELECT statements illustrate the basic difference between the two types of join.
SELECT customer.customer_num, lname, order_num FROM customer, orders
WHERE customer.customer_num = orders.customer_num

Figure G-1

Query 1. Using a Simple Join SELECT customer.customer_num, lname, order_num FROM customer, OUTER orders
WHERE customer.customer_num = orders.customer_num

Figure G-2

Query 2. Using an Outer Join

Both query the same tables (customer and orders) of the same database (stores) through a join on the same column (customer_num). At rst glance, both fetch the same data. The query results, however, are quite different, as the following illustration shows.

How Outer Joins Work

customer_num 104 101 104 106 116 112 117 110 111 115 104 117 104 106 110

lname Higgins Pauli Higgins Watson Parmelee Lawson Sipes Jaeger Keyes Grant Higgins Sipes Higgins Watson Jaeger

order_num 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015

customer_num 101 102 103 104 104 104 104 105 106 106 107 108 109 110 110 111 112 113 114 115 116 117 117 118

lname Pauli Sadler Currie Higgins Higgins Higgins Higgins Vector Watson Watson Ream Quinn Miller Jaeger Jaeger Keyes Lawson Beatty Albertson Grant Parmelee Sipes Sipes Baxter

order_num 1002

1001 1003 1011 1013 1004 1014

1008 1015 1009 1006

1010 1005 1007 1012

Figure G-3

Query 1 Results

Query 2 Results

By using a simple join, Query 1 fetches a list of only those customers who have items on order, while Query 2 fetches a list of all customers by using an outer join. Once you understand how similar queries can produce such dissimilar results, you can begin to use outer joins effectively. The obvious differences between the two kinds of joins are as follows:

A simple join discards all rows that do not satisfy the join condition. An outer join preserves rows that would otherwise be discarded.
The following section discusses outer joins in detail.

How Outer Joins Work

A join queries two or more tables as though they were one. It is as if 4GL creates and then acts upon a single temporary table to produce the query results. 4GL does not actually create such a table to perform a join, but it is helpful to conceptualize a join in these terms. In a simple two-table join, the resulting table contains only those combinations of rows from both tables that satisfy the join condition. In an outer join, the resulting table contains these rows, plus all remaining rows from one of the tables, called the dominant (or preserved) table. The second table is called the subservient table.

G-2

Outer Joins

How Outer Joins Work

Consider two hypothetical tables, employees and depts, which contain the following columns and rows (dash indicates a NULL value):
employees emp_num 2 4 6 5 3 dept_num 105 103 103 102 depts dept_num 102 103 105 dept_loc NY LA SF

Suppose, for example, that you need a list of employee numbers and department locations for all employees, including those employees whose department locations are unknown (represented by NULL values in the employees table). The following query fetches the desired results:
SELECT emp_num, dept_loc FROM employees, OUTER depts WHERE employees.dept_num = depts.dept_num

The keyword OUTER designates depts as the subservient table, making employees the dominant table. 4GL processes the query by the following steps: 1. 4GL applies lters to the subservient table while sequentially applying the join condition to the rows of the dominant table. Rows in the dominant table are retrieved without considering the join, but rows from the subservient table (outer table) are retrieved only if they satisfy the join condition. Any dominant-table rows that do not have a matching row from the subservient table receive a row of NULL values in place of a subservient-table row. The result is a table with the following rows:
emp_num 2 3 4 5 6 dept_num 105 102 103 103 dept_num 105 102 103 103 dept_loc SF NY LA LA

Note: A lter is a condition expressed in a WHERE clause that applies to columns in a single table. For example,
"dept_loc = SF"

or

"emp_num < 105"

Because 4GL applies such lters to the subservient table as it performs the join, the resulting table may contain NULL values that were not present in the subservient table prior to the join.
Outer Joins G-3

How Outer Joins Work

Suppose that the query includes a lter on the dept_loc column:

SELECT emp_num, dept_loc FROM employees, OUTER depts WHERE employees.dept_num = depts.dept_num AND dept_loc != "LA"

At Step 2, the results include more rows of NULL values than the results of the original query:
emp_num 2 3 4 5 6 dept_num 105 102 dept_num 105 102 dept_loc SF NY

The lter removes rows from the depts table where dept_loc is equal to LA. 2. After performing the join, 4GL applies lters to the dominant table (if they exist). 3. 4GL applies the SELECT clause to eliminate unneeded columns, and the query returns the results.
emp_num 2 3 4 5 6 dept_loc SF NY LA LA

In a similar way to the previous example, the following query produces a list of all customers with supplemental information for those customers with items on order. Where orders.customer_num is not equal to

G-4

Outer Joins

How Outer Joins Work

customer.customer_num, 4GL combines a row of NULL values with the corresponding row from the customer table. Because the query does not contain lters, the results preserve every row from the dominant table.
SELECT customer.customer_num, company, order_num, ship_date FROM customer, OUTER orders WHERE customer.customer_num = orders.customer_num Query 3
customer_num company 101 102 103 104 104 104 104 105 106 106 107 108 109 110 110 111 112 113 114 115 116 117 117 118 All Sports Supplies Sports Spot Phils Sports Play Ball! Play Ball! Play Ball! Play Ball! Los Altos Sports Watson & Son Watson & Son Athletic Supplies Quinns Sports Sport Stuff AA Athletics AA Athletics Sports Center Runners & Others Sportstown Sporting Place Gold Medal Sports Olympic City Kids Korner Kids Korner Blue Ribbon Sports order_num ship_date 1002 06/06/1984

Figure G-4

1001 1003 1011 1013

06/05/1984 06/07/1984 06/07/1984 06/11/1984

1004 1014 06/09/1984

1008 06/27/1984 1015 06/11/1984 1009 06/15/1984 1006

1010 1005 1007 1012

06/07/1984 06/08/1984 06/08/1984 06/09/1984

Figure G-5

Query 3 Results

The preceding example queries two tables in the simplest type of outer join. You can, in fact, use outer joins to query any number of tables, producing more types of joins than can be discussed here. The following types are possible when three tables are involved in a query:

You can outer-join the result of a simple join to a third table.

SELECT column-list FROM x, OUTER (y,z) WHERE x.a = y.a AND y.b = z.b

Query 4 performs this kind of join. (See the section Examples later in this chapter.)

Outer Joins G-5

Examples

You can outer-join the result of an outer join to a third table.

SELECT column-list FROM x, OUTER (y, OUTER z) WHERE x.a = y.a AND y.b = z.b

or
SELECT column-list FROM x, OUTER (y, OUTER z) WHERE x.a = z.a AND y.b = z.b

Queries 5 and 6 perform this kind of join. (See the following Examples section.)

You can outer-join two tables individually to a third table, in which case,
join relationships are possible only between the subservient tables and the dominant table. Query 7 performs this kind of join. (See the following Examples section.)
SELECT column-list FROM x, OUTER y, OUTER z WHERE x.a = y.a AND x.b = z.b

When you outer-join several tables to another table, make sure that your WHERE clause does not specify impossible join conditions. The following query attempts a join between two subservient tables:
SELECT column-list FROM x, OUTER y, OUTER z WHERE x.a = y.a AND y.b = z.b

An error results; every outer join must have a dominant table. The following examples use the stores database to demonstrate common multi-table outer joins.

Examples
This query outer-joins the result of a simple join to a third table. It produces a list of all customers with supplemental information (order number, stock number, manufacturer code, and quantity ordered) for those customers who have ordered items manufactured by Anza.
SELECT customer.customer_num, lname, orders.order_num, stock_num, manu_code, quantity FROM customer, OUTER (orders, items) WHERE customer.customer_num = orders.customer_num AND orders.order_num = items.order_num AND manu_code = "ANZ" Query 4

Figure G-6 G-6 Outer Joins

Examples

4GL performs the simple join between orders and items rst, yielding information on all orders for Anza-manufactured items. The outer join combines the customer table with the Anza order information. The query results do not include orders for other items.
customer_num lname 101 102 103 104 104 104 104 104 104 104 105 106 107 108 109 110 110 111 112 112 113 114 115 116 116 117 117 118 Pauli Sadler Currie Higgins Higgins Higgins Higgins Higgins Higgins Higgins Vector Watson Ream Quinn Miller Jaeger Jaeger Keyes Lawson Lawson Beatty Albertson Grant Parmelee Parmelee Sipes Sipes Baxter order_num stock_num manu_code quantity

1003 1003 1003 1011 1013 1013 1013

9 8 5 5 5 6 9

ANZ ANZ ANZ ANZ ANZ ANZ ANZ

1 1 5 5 1 1 2

1008 1008 1006 1006

8 9 5 6

ANZ ANZ ANZ ANZ

1 5 5 1

1010 1005 1005 1012 1012

6 5 6 8 9

ANZ ANZ ANZ ANZ ANZ

1 10 1 1 10

Figure G-7

Query 4 Results

Query 5
This query outer-joins the result of an outer join to a third table. When you use a nested outer join, the query preserves order numbers that Query 4 (using a nested simple join) eliminates. The query results include all orders, whether or not they contain Anza-manufactured items. For other items, the condition
where manu_code = "ANZ"

Outer Joins G-7

Examples

eliminates stock numbers, manufacturer codes, and quantities as before.

SELECT customer.customer_num, lname, orders.order_num, stock_num, manu_code, quantity FROM customer, OUTER (orders, OUTER items) WHERE customer.customer_num = orders.customer_num AND orders.order_num = items.order_num AND manu_code = "ANZ"
customer_num lname 101 102 103 104 104 104 104 104 104 104 104 105 106 106 107 108 109 110 110 110 111 112 112 113 114 115 116 116 117 117 117 118 Pauli Sadler Currie Higgins Higgins Higgins Higgins Higgins Higgins Higgins Higgins Vector Watson Watson Ream Quinn Miller Jaeger Jaeger Jaeger Keyes Lawson Lawson Beatty Albertson Grant Parmelee Parmelee Sipes Sipes Sipes Baxter order_num 1002 stock_num manu_code quantity

1001 1003 1003 1003 1011 1013 1013 1013 1004 1014

9 8 5 5 5 6 9

ANZ ANZ ANZ ANZ ANZ ANZ ANZ

1 1 5 5 1 1 2

1008 1008 1015 1009 1006 1006

8 9

ANZ ANZ

1 5

5 6

ANZ ANZ

5 1

1010 1005 1005 1007 1012 1012

6 5 6 8 9

ANZ ANZ ANZ ANZ ANZ

1 10 1 1 10

Figure G-8

Query 5 Results

In addition to customer, orders, and so on, the following queries include a hypothetical table named custnotes, containing the following columns and data:
customer_num 104 108 115 118 notes sponsors soccer team customer for 20 years opening a second store new customer

G-8

Outer Joins

Examples

Query 6
This query produces a list of all customers with order numbers and selected notes.
SELECT customer.customer_num, orders.order_num, notes FROM customer, OUTER (orders, OUTER custnotes) WHERE customer.customer_num = orders.customer_num AND orders.customer_num = custnotes.customer_num

The outer join between custnotes and orders preserves notes only for customers who also have orders.
customer_num 101 102 103 104 104 104 104 105 106 106 107 108 109 110 110 111 112 113 114 115 116 117 117 118 order_num 1002 notes

1001 1003 1011 1013 1004 1014

sponsors sponsors sponsors sponsors

soccer soccer soccer soccer

team team team team

1008 1015 1009 1006

1010 1005 1007 1012

opening a second store

Figure G-9

Query 6 Results

To preserve notes for customers 108 and 118 who do not have orders, you must outer-join the custnotes table directly with the customer table, as shown in the next query.

Query 7
This query outer-joins two tables individually to a third table. It outer-joins both orders and custnotes to customer (the dominant table).
SELECT customer.customer_num, orders.order_num, notes FROM customer, OUTER orders, OUTER custnotes WHERE customer.customer_num = orders.customer_num AND customer.customer_num = custnotes.customer_num

Outer Joins G-9

Examples

Customer notes now appear, regardless of whether customers have orders.

customer_num 101 102 103 104 104 104 104 105 106 106 107 108 109 110 110 111 112 113 114 115 116 117 117 118 order_num 1002 notes

1001 1003 1011 1013 1004 1014

sponsors sponsors sponsors sponsors

soccer soccer soccer soccer

team team team team

customer for 20 years 1008 1015 1009 1006

opening a second store

1010 1005 1007 1012 new customer

Figure G-10

Query 7 Results

All of the preceding queries fetch information from one table with supplemental information from other tables. When you need similar results, Informix recommends that you use an outer join. When you do not need supplemental information, as is normally the case, use a simple join instead. Be aware that your choice of an outer join can inuence query optimization and processing. You can use the SET EXPLAIN ON statement to examine how the query processor of INFORMIX-4GL performs simple queries, joins, and outer joins.

G-10

Outer Joins

Appendix

ASCII Character Set

Num 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

Char ^@ ^A ^B ^C ^D ^E ^F ^G ^H ^I ^J ^K ^L ^M ^N ^O ^P ^Q ^R ^S ^T ^U ^V ^W ^X ^Y ^Z esc ^\ ^] ^^ ^_ ! " # $ % & ( ) *

Num 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85

Char + , . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U

Num 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127

Char V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~ del

^x = CONTROL-X

H-2

ASCII Character Set

Appendix

Modifying termcap and terminfo

INFORMIX-4GL programs can use function keys and can display color or intensity attributes in screen displays. These and other keyboard and screen options are terminal dependent. To determine terminal-dependent characteristics, INFORMIX-4GL uses the information in the termcap le or in the terminfo directory. INFORMIX-4GL uses the INFORMIXTERM environment variable to determine whether to use termcap or terminfo. For more information about INFORMIXTERM, read the discussion of environment variables in the Environment Variables appendix or in the Preface to the INFORMIX-4GL User Guide .

With INFORMIX-4GL, Informix distributes termcap les that contain additional capabilities for many common terminals (such as the Wyse 50 and the Televideo 950). These capabilities include intensity-change or color-change descriptions or both. This appendix describes these capabilities, as well as the general format of termcap and terminfo entries. Since terminfo does not support color, you can only use INFORMIX-4GL color functionality with termcap. If you want to use color in INFORMIX-4GL, you must set the INFORMIXTERM environment variable to termcap. You can use the information in this appendix, combined with the information in your terminal manual, to modify the contents of your termcap le or terminfo les. This appendix is divided into two main sections, termcap and terminfo. Depending on which you are using, you should read the appropriate section.

termcap

termcap
When INFORMIX-4GL is installed on your system, a termcap le is placed in the etc subdirectory of $INFORMIXDIR. This le is a superset of an operating system termcap le. The Informix termcap le contains additional capabilities for many terminals. You may want to modify this le further in the following instances:

The entry for your terminal has not been modied to include colorchange and intensity-change capabilities.

You want to extend function key denitions. You want to specify or alter the graphics characters used for window
borders.

You want to customize your terminal entry in other ways.

Note: Some terminals cannot support color or graphics characters. You should read this appendix and the user guide that comes with your terminal to determine whether or not the changes described in this appendix are applicable to your terminal.

Format of a termcap Denition

This section describes the general format of termcap entries. For a complete description of termcap, refer to your operating system documentation. A termcap entry contains a list of names for the terminal, followed by a list of the terminals capabilities. There are three types of capabilities:

Boolean capabilities Numeric capabilities String capabilities

All termcap entries have the following format:

ESCAPE is specied as a backslash ( \ ) followed by the letter E, and CTRL is specied as a caret (^). Do not use the ESCAPE or CTRL keys to indicate

escape sequences or control characters in a termcap entry.

Each capability, including the last one in the entry, is followed by a

colon ( : ).

Entries must be dened on a single logical line; a backslash ( \ ) appears

at the end of each line that wraps to the next line.

I-2

Modifying termcap and terminfo

Format of a termcap Denition

Figure I-1 shows a basic termcap entry for the Wyse 50 terminal:
# Entry for Wyse 50: w5|wy50|wyse50: :if=/usr/lib/tabset/std:\ :al=\EE:am:bs:ce=\Et:cm=\E=%+ %+ :cl=\E*:co#80:\ :dc=\EW:dl=\ER:ho=^^:ei=:kh=^^:im=:ic=\EQ:in:li#24:\ :nd=^L:pt:se=\EG0:so=\EG4:sg#1:ug#1:\ :up=^K:ku=^K:kd=^J:kl=^H:kr=^L:kb=:\ :k0=^A@^M:k1=^AA^M:k2=^AB^M:k3=^AC^M:k4=^AD^M:\ :k5=^AE^M:k6=^AF^M:k7=^AG^M:\ :HI=^|:Po=^R:Pe=^T: Wyse 50 termcap Entry

Figure I-1

Note: Comment lines begin with a pound sign ( # ).

Terminal Names
A termcap entry starts with one or more names for the terminal, each separated by a vertical ( | ) bar. For example, the termcap entry for the Wyse 50 terminal starts with the following line:
w5|wy50|wyse50:\

The termcap entry can be accessed using any one of these names.

Boolean Capabilities
A Boolean capability is a two-character code that indicates whether or not a terminal has a specic feature. If the Boolean capability is present in the termcap entry, the terminal has that particular feature. Figure I-2 shows some of the Boolean capabilities for the Wyse 50 terminal:
:bs:am: # bs backspace with CTRL-H # am automatic margins Boolean Capabilities for the Wyse 50

Figure I-2

Modifying termcap and terminfo

I-3

Format of a termcap Denition

Numeric Capabilities
A numeric capability is a two-character code followed by a pound symbol ( # ) and a value. Figure I-3 shows the numeric capabilities for the number of columns and the number of lines on a Wyse 50 terminal:
:co#80:li#24: # co number of columns in a line # li number of lines on the screen Numeric Capabilities for the Wyse 50

Figure I-3

Similarly, sg is a numeric capability that indicates the number of character positions required on the screen for reverse video. The entry :sg#1: indicates that a terminal requires one additional character position when reverse video is turned ON or OFF. If you do not include a particular numeric capability, INFORMIX-4GL assumes that the value is zero.

String Capabilities
A string capability species a sequence that can be used to perform a terminal operation. A string capability is a two-character code followed by an equal sign ( = ) and a string ending at the next delimiter ( : ). Most termcap entries include string capabilities for clearing the screen, cursor movement, Arrow keys, underscore, function keys, and so on. Figure I-4 shows many of the string capabilities for the Wyse 50 terminal:
:ce=\Et:cl=\E*:\ :nd=^L:up=^K:\ :so=\EG4:se=\EG0:\ :ku=^K:kd=^J:kr=^L:kl=^H:\ :k0=^A@^M:k1=^AA^M:k2=^AB^M:k3=^AC^M:

# # # # # # # #

ce=\Et cl=\E* nd=^L up=^K so=\EG4 se=\EG0

clear to end of line clear the screen non-destructive cursor right up one line start stand-out end stand-out

I-4

Modifying termcap and terminfo

Extending Function Key Denitions

Figure I-4

# ku=^K up arrow key # kd=^J down arrow key # kr=^L right arrow key # kl=^H left arrow key # # k0=^A@^M function key F1 # k1=^AA^M function key F2 # k2=^AB^M function key F3 # k3=^AC^M function key F4 String Capabilities for the Wyse 50

Extending Function Key Denitions

INFORMIX-4GL recognizes function keys F1 through F36. These keys correspond to the termcap capabilities k0 through k9, followed by kA through kZ. The termcap entry for these capabilities is the sequence of ASCII characters your terminal sends when you press the function keys (or any other keys you choose to use as function keys). For the Wyse 50 and Televideo 950 terminals, the rst eight function keys send the characters shown in Figure I-5. Function Key termcap Entry F1 k0=^A@^M F2 k1=^AA^M F3 k2=^AB^M F4 k3=^AC^M F5 k4=^AD^M F6 k5=^AE^M F7 k6=^AF^M F8 k7=^AG^M Function Key Entries for the Wyse 50

Figure I-5

You can also dene keys that correspond to the following capabilities:

Insert line (ki) Delete line (kj) Next page (kf) Previous page (kg)

If these keys are dened in your termcap le, INFORMIX-4GL uses them. Otherwise, INFORMIX-4GL uses CTRL-J, CTRL-K, CTRL-M, and CTRL-N, respectively. Note: You can also use the OPTIONS statement to name other function keys or CTRL keys for these operations.

Modifying termcap and terminfo

I-5

Specifying Characters for Window Borders

Specifying Characters for Window Borders

INFORMIX-4GL uses characters dened in the termcap le to draw the border of a window. If no characters are dened in this le, INFORMIX-4GL uses the hyphen ( - ) for horizontal lines, the vertical bar ( | ) for vertical lines, and the plus sign ( + ) for corners.

The termcap le provided with INFORMIX-4GL contains border character denitions for many common terminals. You can look at the termcap le to see if the entry for your terminal has been modied to include these denitions. If your terminal entry does not contain border character denitions, or if you want to specify alternative border characters, you or your system administrator can modify the termcap le. Perform the following steps to modify the denition for your terminal type in the termcap le: 1. Determine the escape sequences for turning graphics mode ON and OFF. This information is located in the manual that comes with your terminal. For example, on Wyse 50 terminals, the escape sequence for entering graphics mode is ESC H^B and the escape sequence for leaving graphics mode is ESC H^C. Note: Terminals without a graphics mode do not have this escape sequence. The procedure for specifying alternative border characters on a non-graphics terminal is discussed at the end of this section. 2. Identify the ASCII equivalents for the six graphics characters that INFORMIX-4GL requires to draw the border. (The ASCII equivalent of a graphics character is the key you would press in graphics mode to obtain the indicated character.) Figure I-6 shows the graphics characters and the ASCII equivalents for a Wyse 50 terminal.
Window Border Graphics ASCII Position Character Equivalent upper left corner 2 lower left corner 1 upper right corner 3 lower right corner 5 horizontal z vertical | 6 Wyse 50 ASCII Equivalents for Border Graphics Characters

Figure I-6

Again, this information should be located in the manual that comes with your terminal. 3. Edit the termcap entry for your terminal.
I-6 Modifying termcap and terminfo

Specifying Characters for Window Borders

Note: You may want to make a copy of your termcap le before you edit it. You can use the TERMCAP environment variable to point to whichever copy of the termcap le you want to access. Use the format termcap-capability=value to enter values for the following termcap capabilities: gs The escape sequence for entering graphics mode. In the termcap le, ESCAPE is represented as a backslash ( \ ) followed by the letter E; CTRL is represented as a caret ( ^ ). For example, the Wyse 50 escape sequence ESC-H CTRL-B is represented as \EH^B. The escape sequence for leaving graphics mode. For example, the Wyse 50 escape sequence ESC-H CTRL-C is represented as \EH^C. The concatenated, ordered list of ASCII equivalents for the six graphics characters used to draw the border. Use the following order:
upper left corner lower left corner upper right corner lower right corner horizontal lines vertical lines

ge gb

Follow these guidelines when you insert information in the termcap entry: 1. Delimit entries with a colon ( : ). 2. End each continuing line with a backslash ( \ ). 3. End the last line in the entry with a colon. For example, if you are using a Wyse 50 terminal, you would add the following information in the termcap entry for the Wyse 50:
:gs=\EH^B:\ :ge=\EH^C:\ :gb=2135z6:\ # # # # # # # sets gs to ESC H CTRL B sets ge to ESC H CTRL C sets gb to the ASCII equivalents of graphics characters for upper left, lower left, upper right, lower right, horizontal, and vertical

If you prefer, you can enter this information in a linear sequence.

:gs=\EH^B:ge=\EH^C:gb=2135z6:\

Modifying termcap and terminfo

I-7

Adding Color and Intensity

Terminals Without Graphics Capabilities

For terminals without graphics capabilities, you must enter a blank value for the gs and ge capabilities. For gb, enter the characters you want INFORMIX-4GL to use for the window border. The following example shows possible values for gs, ge, and gb in an entry for a terminal without graphics capabilities. In this example, window borders would be drawn using underscores ( _ ) for horizontal lines, vertical bars ( | ) for vertical lines, periods ( . ) for the top corners, and vertical bars ( | ) for the lower corners.
:gs=:ge=:gb=.|.|_|: INFORMIX-4GL uses the graphics characters in the termcap le when you specify a window border in an OPEN WINDOW statement.

Adding Color and Intensity

Many of the terminal entries in the Informix termcap le (in the etc subdirectory of $INFORMIXDIR) have been modied to include color or intensity capabilities or both. You can view the termcap le to determine if the entry for your terminal type includes these capabilities. If your terminal entry includes the ZA capability, your terminal is set up for color or intensity or both. If it doesnt, you can add color and intensity capabilities by using the information in this section. The following topics are outlined in this section:

Color and intensity The ZA capability Stack operations Examples

You should understand these topics before you modify your terminal entry.

Color and Intensity Attributes

You can write your INFORMIX-4GL program either for a monochrome or a color terminal and then run the program on either type of terminal. If you set up the termcap les as described here, the color attributes and the intensity attributes are related, as shown in Figure I-7.

I-8

Modifying termcap and terminfo

Adding Color and Intensity

Figure I-7

Number Color Terminal 0 WHITE 1 YELLOW 2 MAGENTA 3 RED 4 CYAN 5 GREEN 6 BLUE 7 BLACK Color-Monochrome Correspondence

Monochrome Terminal NORMAL BOLD BOLD BOLD DIM DIM DIM INVISIBLE

The background for colors is BLACK in all cases. In the Figure I-7, the signies that, if the keyword BOLD is indicated as the attribute, the eld will be RED on a color terminal, or if the keyword DIM is indicated as the attribute, the eld will be BLUE on a color terminal. You can change the color names from the default list by associating different numbers with different color names in a le named colornames in your current directory or in the /incl subdirectory of $INFORMIXDIR. (See the section The colornames File later in this appendix.) In either color or monochrome mode, you can add the REVERSE, BLINK, or UNDERLINE attributes if your terminal supports them. You can select only one of these three attributes.

The ZA String Capability

INFORMIX-4GL uses a parameterized string capability ZA in the termcap le to determine color assignments. Unlike other termcap string capabilities that you set equal to a literal sequence of ASCII characters, ZA is a function string that depends upon four parameters: Parameter 1 (p1) Parameter 2 (p2) Parameter 3 (p3) Parameter 4 (p4) Color number between 0 and 7 (see Figure I-7) 0 = Normal; 1 = Reverse 0 = No-Blink; 1 = Blink 0 = No-Underscore; 1 = Underscore

ZA uses the values of these four parameters and a stack machine to determine which characters to send to the terminal. The ZA function is called and these parameters are evaluated when a color or intensity attribute is encountered in a 4GL program. You can use the information in your terminal manual to set the ZA parameters to the correct values for your terminal. To dene the ZA string for your terminal, you use stack operators to push and pop values onto and off the stack. The next section describes several stack operators. Use these descriptions and the subsequent examples to understand how to dene the string for your terminal.
Modifying termcap and terminfo I-9

Adding Color and Intensity

Stack Operations
The ZA string uses stack operations to either push values onto the stack or pop values off the stack. Typically, the instructions in the ZA string push a parameter onto the stack, compare it to one or more constants, and then send an appropriate sequence of characters to the terminal. More complex operations are often necessary and, by storing the display attributes in static stack machine registers (named a through z), you can achieve terminal-specic optimizations. A summary follows of the different stack operators you can use to write the descriptions. For a complete discussion of stack operators, consult your operating system documentation.

Operators That Send Characters to the Terminal

%d pops a numeric value from the stack and sends a maximum of three digits to the terminal. For example, if the value 145 is at the top of the stack, %d pops the value off the stack and sends the ASCII representations of 1, 4, and 5 to the terminal. If the value 2005 is at the top of the stack, %d pops the value off the stack and sends the ASCII representation of 5 to the terminal. pops a numeric value from the stack and sends a maximum of two digits to the terminal, padding to two places. For example, if the value 145 is at the top of the stack, %2d pops the value off the stack and sends the ASCII representations of 4 and 5 to the terminal. If the value 5 is at the top of the stack, %2d pops the value off the stack and sends the ASCII representations of 0 and 5 to the terminal. pops a numeric value from the stack and sends a maximum of three digits to the terminal, padding to three places. For example, if the value 7 is at the top of the stack, %3d pops the value off the stack and sends the ASCII representations of 0, 0, and 7 to the terminal. pops a single character from the stack and sends it to the terminal.

%2d

%3d

%c

Operators That Manipulate the Stack

%p[1-9] pushes the value of the specied parameter on the stack. The notation for parameters is p1, p2, ... p9. For example, if the value of p1 is 3, %p1 pushes 3 on the stack. %P[a-z] pops a value from the stack and stores it in the specied variable. The notation for variables is Pa, Pb, ... Pz. For example, if
I-10 Modifying termcap and terminfo

Adding Color and Intensity

the value 45 is on the top of the stack, %Pb pops 45 from the stack and stores it in the variable Pb. %g[a-z] gets the value stored in the corresponding variable (P[a-z]) and pushes it on the stack. For example, if the value 45 is stored in the variable Pb, %gb gets 45 from Pb and pushes it on the stack. %c %{n} pushes a single character on the stack. For example, %k pushes k on the stack. pushes an integer constant on the stack. The integer can be any length and can be either positive or negative. For example, %{0} pushes the value 0 on the stack.

%S[a-z] pops a value from the stack and stores it in the specied static variable. (Static storage is nonvolatile since the stored value remains from one attribute evaluation to the next.) The notation for static variables is Sa, Sb, ... Sz. For example, if the value 45 is on the top of the stack, %Sb pops 45 from the stack and stores it in the static variable Sb. This value is accessible for the duration of the INFORMIX-4GL program. %G[a-z] gets the value stored in the corresponding static variable (S[a-z]) and pushes it on the stack. For example, if the value 45 is stored in the variable Sb, %Gb gets 45 from Sb and pushes it on the stack.

Arithmetic Operators
Each arithmetic operator pops the top two values from the stack, performs an operation, and pushes the result on the stack. %+ %%* %/ %m Addition. For example, %{2}%{3}%+ is equivalent to 2+3. Subtraction. For example, %{7}%{3}%- is equivalent to 7-3. Multiplication. For example, %{6}%{3}%* is equivalent to 6*3. Integer division. For example, %{7}%{3}%/ is equivalent to 7/3 and produces a result of 2. Modulus (or remainder). For example, %{7}%{3}%m is equivalent to (7 mod 3) and produces a result of 1.

Modifying termcap and terminfo I-11

Adding Color and Intensity

Bit Operators
The following bit operators pop the top two values from the stack, perform an operation, and push the result on the stack: %& Bit-and. For example, %{12}%{21}%& is equivalent to (12 and 21) and produces a result of 4.
Binary 0 1 1 0 1 1 0 0 0 1 = = Decimal 12 21 and = 4

------------------------0 0 1 0 0

%|

Bit-or. For example, %{12}%{21}%| is equivalent to (12 or 21) and produces a result of 29.
Binary 0 1 1 0 1 1 0 0 0 1 = = Decimal 12 21 or = 29

------------------------1 1 1 0 1

%^

Exclusive-or. For example, %{12}%{21}%^ is equivalent to (12 exclusive-or 21) and produces a result of 25.
Binary 0 1 1 0 1 1 0 0 0 1 = = Decimal 12 21 exclusive or = 25

------------------------1 1 0 0 1

The following unary operator pops the top value from the stack, performs an operation, and pushes the result on the stack:

I-12

Modifying termcap and terminfo

Adding Color and Intensity

%~

Bitwise complement. For example, %{25}%~ results in a value of -26, as shown in the following display.
Binary 0 0 0 1 1 0 0 1 = Decimal 25 Complement = -26

---------------------------1 1 1 0 0 1 1 0

Logical Operators
The following logical operators pop the top two values from the stack, perform an operation, and push the logical result (either 0 for false or 1 for true) on the stack: %= Equal to. For example, if the parameter p1 has the value 3, the expression %p1%{2}%= is equivalent to 3=2 and produces a result of 0 (false). Greater than. For example, if the parameter p1 has the value 3, the expression %p1%{0}%> is equivalent to 3>0 and produces a result of 1 (true). Less than. For example, if the parameter p1 has the value 3, the expression %p1%{4}%< is equivalent to 3<4 and produces a result of 1 (true).

%>

%<

The following unary operator pops the top value from the stack, performs an operation, and pushes the logical result (either 0 or 1) on the stack. %! Logical negation. This operator produces a value of zero for all nonzero numbers and a value of 1 for zero. For example, %{2}%! results in a value of 0, and %{0}%! results in a value of 1.

Conditional Statements
The condition statement IF-THEN-ELSE has the following format:
%? expr %t thenpart %e elsepart %;

The %e elsepart is optional. You can nest conditional statements in the thenpart or the elsepart. When INFORMIX-4GL evaluates a conditional statement, it pops the top value from the stack and evaluates it as either true or false. If the value is true, INFORMIX-4GL performs the operations after the %t; otherwise it performs the operations after the %e (if any).
Modifying termcap and terminfo I-13

Adding Color and Intensity

For example, the expression

%?%p1%{3}%=%t;31%;

is equivalent to
if p1 = 3 then print ";31"

Assuming that p1 has the value 3, INFORMIX-4GL performs the following steps:

%? does not perform an operation but is included to make the conditional

statement easier to read.

%p1 pushes the value of p1 on the stack. %{3} pushes the value 3 on the stack. %= pops the value of p1 and the value 3 from the stack, evaluates the
Boolean expression p1=3, and pushes the resulting value 1 (true) on the stack.

%t pops the value from the stack, evaluates 1 as true, and executes the
operations after %t. (Since ;31 is not a stack machine operation, INFORMIX-4GL prints ;31 to the terminal.)

%; terminates the conditional statement.

I-14

Modifying termcap and terminfo

Adding Color and Intensity

Summary of Operators
Figure I-8 summarizes the allowed operations:
Operation %d %2d %3d %c %p[1-9] %P[a-z] %g[a-z] %c %{n} %S[a-z] %G[a-z] %+ %%* %/ %m %& %| %^ %~ %= %> %< %! %? Description write pop() in decimal format write pop() in 2-place decimal format write pop() in 3-place decimal format write pop() as a single character push ith parameter pop and store variable get variable and push on stack push char constant push integer constant pop and store static variable get static variable and push addition. push(pop() op pop()) subtraction. push(pop() op pop()) multiplication. push(pop() op pop()) integer division. push(pop() op pop()) modulus. push(pop() op pop()) bit and. push(pop() op pop()) bit or. push(pop() op pop()) bit exclusive or. push(pop() op pop()) bitwise complement. push(op pop()) equal to. push(pop() op pop()) greater than. push(pop() op pop()) less than. push(pop() op pop()) logical negation. push(op pop()) expr %t thenpart %e elsepart %; if-then-else; the %e elsepart is optional. else-ifs are possible (cs are conditions): %? c1 %t...%e c2 %t...%e c3 %t...%e...%; nested ifs allowed.

Figure I-8

all other characters are written to the terminal; use %% to write %. Stack Operations

Modifying termcap and terminfo

I-15

Adding Color and Intensity

Examples
To illustrate, consider the monochrome Wyse terminal. Figure I-9 shows the escape sequences for various display characteristics.
ESC G 0 ESC G 1 ESC G 2 ESC G 4 ESC G 5 ESC G 6 ESC G 8 ESC G 9 ESC G : ESC G < ESC G = ESC G > Wyse Escape Sequences Normal blank(invisible) blink Reverse Reverse and blank Reverse and blink Underscore Underscore and blank Underscore and blink Underscore and reverse Underscore, reverse, and blank Underscore, reverse, and blink

Figure I-9

The characters after G form an ASCII sequence from the character 0 (zero) through ?. You can generate the character by starting with 0 and adding 1 for blank, 2 for blink, 4 for reverse, and 8 for underline. You can construct the termcap entry in stages, as outlined in the following display. %pi refers to pushing the ith parameter on the stack. The designation for ESCAPE is \E. The termcap entry for the Wyse terminal must contain the following ZA entry in order for INFORMIX-4GL monochrome attributes such as REVERSE and BOLD to work correctly:
ZA = EG %0 %?%p1%{7}%=%t%{1}%| %e%p1%{3}%> %p1%{7}%<%&%t%{64}%| %;%; %?%p2%t%{4}%|%; %?%p3%t%{2}%|%; %?%p4%t%{8}%|%; %c: #print EG #push 0 (normal) on the stack #if p1 = 7 (invisible), set #the 1 bit (blank); #if p1 > 3 and < 7, set the 64 flag (dim); # # #if p2 is set, set the 4 bit (reverse) #if p3 is set, set the 2 bit (blink) #if p4 is set, set the 8 bit (underline) #print whatever character #is on top of the stack

I-16

Modifying termcap and terminfo

Adding Color and Intensity

You then concatenate these lines as a single string that ends with a colon and has no embedded NEWLINEs. The actual ZA entry for the Wyse 50 terminal follows:
ZA = \EG%0%?%p1%{7}%=%t%{1}%|%e%p1%{3}%>%p1%{7}%<%&%t%{64} %|%;%;%?%p2%t%{4}%|%;%?%p3%t%{2}%|%;%?%p4%t%{8}%|%;%c:

The next example is for the ID Systems Corporation ID231, a color terminal. On this terminal, to set color and other characteristics you must enclose a character sequence between a lead-in sequence (ESC [ 0) and a terminating character (m). The rst in the sequence is a two-digit number that determines whether the assigned color is in the background (30) or in the foreground (40). The next is another two-digit number that is the other of 30 or 40, incremented by the color number. These characters are followed by 5 if there is blinking, and by 4 for underlining. The code in Figure I-10 sets up the entire escape sequence:
ZA = \E[0; %?%p1%{0}%=%t%{7} %e%p1%{1}%=%t%{3} %e%p1%{2}%=%t%{5} %e%p1%{3}%=%t%{1} %e%p1%{4}%=%t%{6} %e%p1%{5}%=%t%{2} %e%p1%{6}%=%t%{4} %e%p1%{7}%=%t%{0}%; %?%p2%t30;%{40}%+%2d %e40;%{30}%+%2d%; %?%p3%t;5%; %?%p4%t;4%; m Figure I-10 Sample ZA String for ID231 #print lead-in #encode color number (translate # from Figure I-7 to the number # for the ID231) # # # # # #if p2 is set, print 30 and # 40 + color number (reverse) # else print 40 and # 30 + color number (normal) #if p3 is set, print 5 (blink) #if p4 is set, print 4 (underline) #print m to end character # sequence

When you concatenate these strings, the termcap entry is as shown in Figure I-11.
ZA =\E[0;%?%p1%{0}%=%t%{7}%e%p1%{1}%=%t%{3}%e%p1%{2}%= %t%{5}%e%p1%{3}%=%t%{1}%e%p1%{4}%=%t%{6}%e%p1%{5}%=%t% {2}%e%p1%{6}%=%t%{4}%e%p1%{7}%=%t%{0}%;%?%p2%t30;%{40} %+%2d%e40;%{30}%+%2d%;%?%p3%t;5%;%?%p4%t;4%;m Concatenated ZA String for ID231

Figure I-11

Modifying termcap and terminfo

I-17

The colornames File

In addition to the ZA capability, you can use other termcap capabilities. ZG is the number of character positions on the screen occupied by the attributes of ZA. Like the sg numeric capability, ZG is not required if no extra character positions are needed for display attributes. The value for the ZG entry is usually the same value as for the sg entry.

The colornames File

You can create a colornames le if you want to change the default assignment of the names of colors. A colornames le is an ASCII le that changes the keywords that you use to write INFORMIX-4GL programs. It does not affect the colors produced by your terminal. The format for the colornames le follows:
name ... number ...

Explanation
name number is the identier of a color. is an integer from 0 to 7.

Notes
1. Each color name and number must be on a separate line. They should be separated by one or more spaces or tabs. 2. name cannot be a reserved word and must be unique in the colornames le. You cannot assign the same name to more than one number. 3. Unless you redene them in the colornames le to have a different number, the default color-name keywords that are listed in the Color and Intensity section of this appendix (and in the next example) retain their meaning, even when you assign another name to that color number.

Examples
If you created a colornames le to set up the default assignment of names to color numbers, colornames would look as follows:
WHITE YELLOW MAGENTA RED CYAN 0 1 2 3 4

I-18

Modifying termcap and terminfo

The colornames File

GREEN BLUE BLACK

5 6 7

If you wanted to change CYAN to AQUA and MAGENTA to ORANGE as color names, set colornames as follows:
AQUA ORANGE 4 2

You could use either CYAN or AQUA in your INFORMIX-4GL program and get the same color. Similarly, use of MAGENTA or ORANGE produces the same color. If you want to change the meaning of the default color names, you can reassign them in colornames:
RED 2

In this case when you use RED in a program, the color you get is the same as has been assigned to MAGENTA. If you have not assigned a name to number 3, you are not able to get the color that RED originally represented. The syscolatt table and the ATTRIBUTE clauses of various 4GL statements can recognize numeric color codes and non-default names for colors. You can specify these names or numbers in place of the color keywords that are documented in Chapter 7 and in the description of the upscol utility in Appendix E. Note: You cannot, however, specify numeric codes or non-default names from colornames in the ATTRIBUTES section of a screen form.

Modifying termcap and terminfo

I-19

terminfo

terminfo
If you have set the INFORMIXTERM environment variable to terminfo, INFORMIX-4GL uses the terminfo directory indicated by the TERMINFO environment variable (or /usr/lib/terminfo if TERMINFO is not set). INFORMIX-4GL uses the information in terminfo to draw window borders, dene function keys, and display certain intensity attributes. You may want to modify a le in the terminfo directory in the following instances:

You want to extend function key denitions. You want to specify or change the graphics characters used for window
borders.

You want to customize your terminal entry in other ways.

Note: If you use terminfo (instead of termcap), you cannot use color attributes with INFORMIX-4GL. To use color attributes with INFORMIX-4GL, you must use termcap. Some terminals cannot support graphics characters. You should read this appendix and the user guide that comes with your terminal to determine whether or not the changes described in this appendix are applicable to your terminal. To modify a terminfo le, you need to be familiar with the following:

The format of terminfo entries The infocmp program The tic program
This information is summarized in this appendix; however, you should refer to your operating system documentation for a complete discussion.

Format of a terminfo Entry

terminfo is a directory that contains a le for each terminal name that is dened. Each le contains a compiled terminfo entry for that terminal. This section describes the general format of terminfo entries. For a complete description of terminfo, refer to your operating system documentation.

I-20

Modifying termcap and terminfo

Format of a terminfo Entry

A terminfo entry contains a list of names for the terminal, followed by a list of the terminals capabilities. There are three types of capabilities:

Boolean capabilities Numeric capabilities String capabilities

All terminfo entries have the following format:

ESCAPE is specied as a backslash ( \ ) followed by the letter E, and CTRL is specied as a caret (^). Do not use the ESCAPE or CTRL keys to indicate

escape sequences or control characters in a terminfo entry.

Each capability, including the last one in the entry, is followed by a

comma ( , ). Figure I-12 shows a basic terminfo entry for the Wyse 50 terminal:
. Entry for Wyse 50: w5|wy50|wyse50, am, cols#80, lines#24, cuul=^K, clear=^Z, home=^^, cuf1=^L, cup=\E=%p1%\s%+%c%p2%\s%+%c, bw, ul, bel=^G, cr=\r, cud1=\n, cub1=\b, kpb=\b, kcudl=\n, kdub1=\b, nel=\r\n, ind=\n, xmc#1, cbt=\EI, Wyse 50 terminfo Entry

Figure I-12

Note: Comment lines begin with a period ( . ).

Terminal Names
A terminfo entry starts with one or more names for the terminal (each separated by a vertical bar ( | )). For example, the terminfo entry for the Wyse 50 terminal starts with the following line:
w5|wy50|wyse50,

The terminfo entry can be accessed using any one of these names.

Boolean Capabilities
A Boolean capability is a two- to ve-character code that indicates whether or not a terminal has a specic feature. If the Boolean capability is present in the terminfo entry, the terminal has that particular feature.

Modifying termcap and terminfo

I-21

Format of a terminfo Entry

Figure I-13 shows some of the Boolean capabilities for the Wyse 50:
bw,am, . bw backward wrap . am automatic margins Boolean Capabilities for the Wyse 50

Figure I-13

Numeric Capabilities
A numeric capability is a two- to ve-character code followed by a pound symbol ( # ) and a value. Figure I-14 shows the numeric capabilities for the number of columns and the number of lines on a Wyse 50 terminal:
cols#80,lines#24, . cols number of columns in a line . lines number of lines on the screen Numeric Capabilities for the Wyse 50

Figure I-14

String Capabilities
A string capability species a sequence that can be used to perform a terminal operation. A string capability is a two- to ve-character code followed by an equal sign ( = ) and a string ending at the next delimiter ( , ). Most terminfo entries include string capabilities for clearing the screen, cursor movement, arrow keys, underscore, function keys, and so on. Figure I-15 shows many of the string capabilities for the Wyse 50 terminal:
el=\ET,clear=E*, cuf1=^L,cuu1=^K, smso=\EG4,rmso=\EG0, kcuu1=^K,kcud1=^J,kcuf1=^L,kcub1=^H, kf0=^A@^M,kf1=^AA^M,kf2=^AB^M,kf3=^AC^M, . . . . . . . . el=\Et clear=\E* cufl=^L cuul=^K smso=\EG4 rmso=\EG0 clear to end of line clear the screen non-destructive cursor right up one line start stand-out end stand-out

I-22

Modifying termcap and terminfo

Extending Function Key Denitions

Figure I-15

. kcuul=^K up arrow key . kcudl=^J down arrow key . kcufl=^L right arrow key . kcubl=^H left arrow key . . kf0=^A@^M function key F1 . kf1=^AA^M function key F2 . kf2=^AB^M function key F3 . kf3=^AC^M function key F4 String Capabilities for the Wyse 50

Extending Function Key Denitions

INFORMIX-4GL recognizes function keys F1 through F36. These keys correspond to the terminfo capabilities kf0 through kf36. The terminfo entry for these capabilities is the sequence of ASCII characters that your terminal sends when you press the function keys (or any other keys you choose to use as function keys). For the Wyse 50 and Televideo 950 terminals, the rst eight function keys send the characters shown in Figure I-16. Function Key terminfo Entry F1 kf0=^A@^M F2 kf1=^AA^M F3 kf2=^AB^M F4 kf3=^AC^M F5 kf4=^AD^M F6 kf5=^AE^M F7 kf6=^AF^M F8 kf7=^AG^M Function Key Entries for the Wyse 50

Figure I-16

You can also dene keys that correspond to the following capabilities:

Insert line (kill) Delete line (kdll) Next page (knp) Previous page (kpp)

If these keys are dened in your terminfo le, INFORMIX-4GL uses them. Otherwise, INFORMIX-4GL uses CTRL-J, CTRL-K, CTRL-M, and CTRL-N, respectively. Note: You can also use the OPTIONS statement to name other function keys or CTRL keys for these operations.

Modifying termcap and terminfo

I-23

Specifying Characters for Window Borders

Specifying Characters for Window Borders

INFORMIX-4GL uses characters dened in the terminfo les to draw the border of a window. If no characters are dened in this le, INFORMIX-4GL uses

the hyphen ( - ) for horizontal lines, the vertical bar ( | ) for vertical lines, and the plus sign ( + ) for corners. You can look at the terminfo source le (using infocmp) to see if the entry for your terminal includes these denitions. (Look for the acsc capability, described later in this section.) If the le for your terminal does not contain border character denitions, or if you want to specify alternative border characters, you or your system administrator can modify the terminfo source le. You can refer to your operating system documentation for a complete description of how to decompile terminfo entries using the infocmp program. Perform the following steps to specify border characters in the terminfo source le for your terminal: 1. Determine the escape sequences for turning graphics mode on and off. This information is located in the manual that comes with your terminal. For example, on Wyse 50 terminals, the escape sequence for entering graphics mode is ESC H^B and the escape sequence for leaving graphics mode is ESC H^C. Note: Terminals without a graphics mode do not have this escape sequence. The procedure for specifying alternative border characters on a non-graphics terminal is discussed at the end of this section. 2. Identify the ASCII equivalents for the six graphics characters that INFORMIX-4GL requires to draw the border. (The ASCII equivalent of a graphics character is the key you would press in graphics mode to obtain the indicated character.) Figure I-17 shows the graphics characters and the ASCII equivalents for a Wyse 50 terminal.

I-24

Modifying termcap and terminfo

Specifying Characters for Window Borders

Figure I-17

Windown Border Graphics ASCII Position Character Equivalent 2 upper left corner lower left corner 1 upper right corner 3 lower right corner 5 horizontal z vertical | 6 Wyse 50 ASCII Equivalents for Border Graphics Characters

Again, this information should be located in the manual that comes with your terminal. 3. Edit the terminfo source le for your terminal. (You can decompile it using infocmp redirected to a le.) Note: You may want to make a copy of your terminfo directory before you edit les. You can use the TERMINFO environment variable to point to whichever copy of the terminfo directory you want to access. Use the format terminfo-capability=value to enter values for the following terminfo capabilities: smacs The escape sequence for entering graphics mode. In a terminfo le, ESCAPE is represented as a backslash ( \ ) followed by the letter E; CTRL is represented as a caret ( ^ ). For example, the Wyse 50 escape sequence ESC-H CTRL-B is represented as \EH^B. rmacs The escape sequence for leaving graphics mode. For example, the Wyse 50 escape sequence ESC-H CTRL-C is represented as \EH^C. acsc The concatenated, paired list of ASCII equivalents for the six graphics characters used to draw the border. You can specify the characters in any order, but you must pair the ASCII equivalents for your terminal with the following system default characters:

Modifying termcap and terminfo

I-25

Specifying Characters for Window Borders

Figure I-18

System Default Position Character upper left corner l lower left corner m upper right corner k lower right corner j horizontal lines q vertical lines x System Default Characters for Border Positions

Use the following format to specify the acsc value: defnewdefnew . . . where def is the default character for a particular border character and new is that terminals equivalent for the same border character. For example, on the Wyse 50 terminal, given the ASCII equivalents in Figure I-17 and the system default characters in Figure I-18, the acsc capability would be set as shown in Figure I-19.
Figure I-19 acsc=l2m1k3j5qzx6 Wyse 50 acsc setting

4. Use tic to recompile the modied terminfo le. See your operating system documentation for a description of the tic program. The following example shows the full setting for specifying alternative border characters on the Wyse 50:
smacs=\EH^B, rmacs=\EH^C, acsc=l2m1k3j5qzx6, . . . . . . . sets smacs to ESC H CTRL B sets rmacs to ESC H CTRL C sets acsc to the ASCII equivalents of graphics characters for upper left (l), lower left (m), upper right (k), lower right (j), horizontal (q), and vertical (x)

If you prefer, you can enter this information in a linear sequence.

smacs=\EH^B,rmacs=\EH^C,acsc=l2m1k3j5qzx6,

Terminals Without Graphics Capabilities

For terminals without graphics capabilities, you must enter a blank value for the smacs and rmacs capabilities. For acsc, enter the characters that you want INFORMIX-4GL to use for the window border.

I-26

Modifying termcap and terminfo

Color and Intensity

The following example shows possible values for smacs, rmacs, and acsc in an entry for a terminal without graphics capabilities. In this example, window borders would be drawn using underscores ( _ ) for horizontal lines, vertical bars ( | ) for vertical lines, periods ( . ) for the top corners, and vertical bars ( | ) for the lower corners.
smacs=,rmacs=,acsc=l.m|k.j|q_x|, INFORMIX-4GL uses the graphics characters in the terminfo le when you specify a window border in an OPEN WINDOW statement.

Color and Intensity

If you use terminfo, you cannot use color nor the following intensity attributes in your INFORMIX-4GL programs:
BOLD DIM INVISIBLE BLINK

If you specify these attributes in your INFORMIX-4GL code, they are ignored. If the terminfo entry for your terminal contains the ul and so attributes, you can use the UNDERLINE and REVERSE intensity attributes. You can see if your terminfo entry includes these capabilities by using the infocmp program. Refer to your operating system documentation for information about infocmp. If you want to use color and intensity in your INFORMIX-4GL programs, you must use termcap (by setting the INFORMIXTERM environment variable to termcap, and by setting the TERMCAP environment variable to $INFORMIXDIR/etc/termcap). For more information, refer to the Environment Variables appendix and the Preface in the INFORMIX-4GL User Guide.

Modifying termcap and terminfo

I-27

Color and Intensity

I-28

Modifying termcap and terminfo

Appendix

J
Working with DATETIME and INTERVAL Data
The DATETIME and INTERVAL data types provide a way of storing moments in time and the spans between moments. The DATETIME data type holds a value that represents a single point in time. You choose how precisely a DATETIME value is stored; its precision can range from years through fractions of a second. The INTERVAL data type holds a value that represents a span of time. It can represent either a span of years and months, or else a span of days, hours, minutes, seconds, and fractions of a second. You can specify DATETIME and INTERVAL values in a form that explicitly identies not only the value but also the data type (DATETIME or INTERVAL) and the precision, or you can enter values as quoted character strings that include only the values. The explicit form, sometimes called a literal, appears throughout this appendix (except as noted), but character strings (which omit the data type and eld names) may be required in interactive operations, such as query by example or data entry through screen forms. You can manipulate DATETIME and INTERVAL values in a number of ways. You can enter them as data, you can use them in relational expressions, and you can manipulate them arithmetically. This appendix supplies you with guidelines on how you can use DATETIME and INTERVAL values. Note, however, that many of the examples presented here are fragmentary. That is, they do not include the

DATETIME Columns

full syntax necessary for an executable statement. (The sectionData Manipulation Statements presents examples of complete SQL statements that use DATETIME and INTERVAL values.)

DATETIME Columns
Use the DATETIME data type for columns or variables in which you want to store values that represent a specic point in time. The DATETIME data type is composed of a contiguous sequence of elds that represent each component of time that you want to record. This is the syntax for dening a DATETIME column or program variable:
identier DATETIME rst TO last

Here rst and last are elds taken from the following list:
Field YEAR MONTH DAY HOUR MINUTE SECOND FRACTION Valid Entries A year, numbered from 1 to 9999. A month, numbered from 1 to 12. A day, numbered from 1 to 31, as appropriate to the month in question. An hour, numbered from 0 (midnight) to 23. A minute, numbered from 0 to 59. A second, numbered from 0 to 59. A fraction of a second with up to ve decimal digits. The default scale is three digits (thousandth of a second). You can explicitly change this by writing FRACTION (n), where n is the desired number of digits from 1 to 5.

A DATETIME column or variable need not include all elds from YEAR to FRACTION. It can be a subset of elds, or even a single eld (if rst and last are identical). You can dene a DATETIME column or variable to include only the elds that you need. For example, you can specify MONTH TO HOUR to include only MONTH, DAY, and HOUR. Since the elds are contiguous, they include all elds from rst to last in the sequence listed above. But you cannot specify HOUR TO YEAR, because rst cannot be a smaller unit than last. Operations involving DATETIME values that do not include precision up to YEAR use the system date to supply any additional precision required. When the rst eld is DAY and the current month has less than 31 days, you can

J-2

Working with DATETIME and INTERVAL Data

Specifying DATETIME Values

encounter unexpected results. For example, assume it is February, and you want to insert data left over from January 31 into the table created by the following statement:
CREATE TABLE mytable (mytime DATETIME DAY TO MINUTE) INSERT INTO mytable VALUES (DATETIME(31 12:30) DAY TO MINUTE)

Because the column mytime does not include the month or year, the current month and year are used to evaluate whether the inserted value is within acceptable bounds. February has only 28 (or 29) days, so no value for DAY can be larger than 28 (or 29). The INSERT statement in this example would fail, because the value 31 for DAY is out of range for February. If your application requires that DATETIME inserts span months in this way, always dene DATETIME columns with precision up to at least MONTH.

Specifying DATETIME Values

There is a rigid syntax that you must observe when you insert DATETIME constants into DATETIME columns or variables. If you use the literal form, you must supply the actual date and time values, with proper delimiters between the elds, and a list of the rst and last elds that you are specifying. (A later section of this appendix describes character string formats.) Just as you can dene a DATETIME column or variable to be only a subset of all possible elds, you can also specify values that contain just a subset of the declared elds of a DATETIME column or variable. For example, you can enter a value consisting of just MONTH, DAY, and HOUR into a column that is dened as YEAR TO MINUTE. Each value, however, must always contain information for a contiguous sequence of elds. For example, you cannot specify a value for just MONTH and HOUR. The entry must include a value for DAY as well. When you specify a value with fewer elds than the dened column or variable, the value that you enter is automatically expanded to ll all the dened elds. If you omit a more signicant eld (that is, a eld of a larger unit than any value that you supply), that eld is automatically lled with the system date. In the previous example, YEAR is omitted, so the current year is automatically inserted into your entry. Alternatively, if you omit a less signicant eld, that eld is lled with zeros (or one for MONTH and DAY ) in your entry. In the previous example, MINUTE is left out, so zeros are inserted into the MINUTE eld for your entry. Consider the following example:
CREATE TABLE mytable (mytime DATETIME YEAR TO MINUTE) INSERT INTO mytable VALUES (DATETIME (8-31 12) MONTH TO HOUR) Working with DATETIME and INTERV Data AL J-3

Specifying DATETIME Values

Even though the column mytime has a dened precision of YEAR to MINUTE, you can supply information for only MONTH to HOUR. The entered value is automatically expanded to ll the column. If the current year is 1989, the actual inserted value becomes:
DATETIME (1989-8-16 12:00) YEAR TO MINUTE

Notice that the current year, in this example 1989, has been added automatically, along with zeros for the MINUTE eld. The current date is also used to evaluate whether a DATETIME value that does not include precision up to YEAR is an acceptable date. This can cause problems when the largest precision of the value is DAY. For example, assume the current month is September, and you attempt to execute the following statements:
CREATE TABLE mytable (mytime DATETIME DAY TO MINUTE) INSERT INTO mytable VALUES (DATETIME (31 12) DAY TO HOUR)

Before the row is inserted, the validity of the DATETIME value is checked against the current date. Because September has only 30 days, the 31 for DAY is out of range and will produce an error. As a result, you cannot insert this row during a month that has fewer than 31 days. Caution: In order to eliminate the risk of processing difculties during months with fewer than 31 days, do not create DATETIME columns or variables with a rst precision of DAY, and do not enter DATETIME values with DAY as the eld of largest precision. When you enter a DATETIME literal, you must include a qualier that species both the rst (largest) and last (smallest) eld in the value to be entered. Including the qualier is necessary because, as noted earlier, the value that you are entering can contain fewer elds than dened for that column or variable. Acceptable keywords for the rst and last elds are identical to the list of valid DATETIME elds displayed previously. A valid entry contains the DATETIME name, the values to be entered, and the eld qualier. Use the syntax rst-eld TO last-eld to qualify the DATETIME value. For example, in the following entry, YEAR TO FRACTION indicates that values for all possible elds are included in the values listed between the parentheses. The order of entry and the type of delimiter identify which value corresponds to each eld.
DATETIME (1985-5-2 14:05:00.000) YEAR TO FRACTION

J-4

Working with DATETIME and INTERVAL Data

INTERVAL Columns

The following examples illustrate values that do not include all elds:
DATETIME DATETIME DATETIME DATETIME DATETIME (89-8-16) YEAR TO DAY (16 12:23) DAY TO MINUTE (21.234) SECOND TO FRACTION (32) SECOND TO SECOND (.0032) FRACTION TO FRACTION(4)

When YEAR is given as a two-digit number, as in the rst example, it is automatically changed to 19xx (1989 in this case). If you want to specify years 1-99, pad the entry with a preceding zero(s), for example 089 or 0089. When a value occupies only one eld, the rst and last qualiers are the same. If the rst and last qualiers are both FRACTION, you specify the precision only for the last eld. Values for the elds are written as integers and are separated by delimiters. All eld values are two-digit integers, except for the YEAR (four digits) and FRACTION (n digits) elds. The following delimiters are used with DATETIME values:
Delimiter hyphen ( - ) space ( ) colon ( : ) period ( . ) Placement in DATETIME Expression Between the YEAR and MONTH, and between the MONTH and DAY portions of the value. Between the DAY and HOUR portions of the value. Between the HOUR and MINUTE, and MINUTE and SECOND portions of the value. Between the SECOND and FRACTION portions of the value.

You use the same delimiters when DATETIME values are expressed as character strings.

INTERVAL Columns
Like the DATETIME data type, the INTERVAL data type is composed of a contiguous sequence of elds. Here is the syntax for dening an INTERVAL column: identier INTERVAL rst TO last Here rst and last are elds taken from one of the following two lists:
Field YEAR MONTH OR Working with DATETIME and INTERV Data AL J-5 Valid Entries A number of years. A number of months.

Specifying INTERVAL Values

DAY HOUR MINUTE SECOND FRACTION

A number of days. A number of hours. A number of minutes. A number of seconds. A fraction of a second, with up to ve decimal digits. The default scale is three digits (thousandth of a second). You can change this by explicitly writing FRACTION(n), where n is the desired number of digits from 1 to 5.

As with a DATETIME column, you can dene an INTERVAL column to include only the elds that you need. An INTERVAL value can contain either YEAR and MONTH information or DAY through FRACTION information, but not a combination of both. The reason for this is that the INTERVAL data type is designed specically to represent a span of time independent of actual dates. The number of days in a month depends on which month it is. INTERVAL data cannot be month-dependent; therefore, it is not possible to combine months and days in an INTERVAL value.

Specifying INTERVAL Values

Like its DATETIME counterpart, a value that you enter into an INTERVAL column need not include all the declared elds. For example, you can enter a value consisting of HOUR, MINUTE, and SECOND elds into a column dened as DAY TO SECOND. A value must always consist, however, of a contiguous sequence of elds. For example, you cannot specify just HOUR and SECOND values; you must include MINUTE as well. When you enter a value in an INTERVAL column, you must include a qualier that species both the rst (largest) and last (smallest) elds in the value, just as for DATETIME values. In addition, you can specify the precision of the rst eld (and of the the last eld if it is FRACTION). Acceptable qualiers for the rst eld and last eld are identical to the list of INTERVAL elds previously displayed, with the same restriction that YEAR and MONTH cannot be combined with the smaller elds. You write INTERVAL values in the same literal format as DATETIME values. A valid entry contains the INTERVAL name, the values to be entered, and the eld qualier. For example, the following entries are valid INTERVAL values:
INTERVAL (5-3) YEAR TO MONTH INTERVAL (9) MONTH TO MONTH INTERVAL (12:23) HOUR TO MINUTE

J-6

Working with DATETIME and INTERVAL Data

Specifying INTERVAL Values

Each entry represents a span of time: 5 years and 3 months; 9 months; and 12 hours and 23 minutes, respectively. None of the entries refer to a specic point in time. For example, the nine-month interval could represent a span from any single year or across any two years. When a value contains just one eld, the rst and last qualiers are the same. If the rst and last qualiers are both FRACTION, you can only specify the precision in the last eld. The rst eld in an INTERVAL value can be up to nine digits in size (except for FRACTION, which cannot be more than ve digits), but if the value is greater than the default number of digits allowed for that eld, you must explicitly identify the number of signicant digits in the value you are entering. By default, you are allowed up to four digits in a year, three digits in a fraction, and two digits in all other elds. If you need more digits than the default, enter the number of required digits (between parentheses) after the eld qualier.
INTERVAL INTERVAL INTERVAL INTERVAL (10000-2) YEAR(5) TO MONTH (127) MONTH(3) TO MONTH (365 0:23) DAY(3) TO MINUTE (1421 36:25:54.93721) DAY(4) TO FRACTION(5)

The rst example illustrates how you can specify a span of 10,000 years by including the number ve (5) after the YEAR. The second example allows a three-digit MONTH entry. Notice that the number is attached to the rst qualier. You will get a syntax error if you attach the number to the last qualier. The third example is a DAY TO MINUTE span of 1 year and 23 minutes. This illustrates how you can represent values of any length by converting years and months into their corresponding number of days. Note also how you can include a zero for the HOUR eld in order to enter a value just for MINUTE. The last example shows how you can specify the precision of both rst and last when FRACTION is the last eld. Non-default precisions are a feature of INTERVAL data. An error results if you use this notation to specify any DATETIME eld except FRACTION.
INTERVAL data follow normal date and time conventions concerning the range of acceptable values that you can enter. An error results if you exceed the possible values for a given eld. Note the following examples: INTERVAL (5-13) YEAR TO MONTH INTERVAL (6-1) YEAR TO MONTH

The rst example causes an error because 13 months is more than a year. The second example correctly expresses the same span of time.

Working with DATETIME and INTERV Data AL

J-7

DATETIME and INTERVAL Values as Character Strings

The values for the elds are written as integers and are separated by delimiters. The following delimiters are used with INTERVAL values:
Delimiter hyphen ( - ) space ( ) colon ( : ) period ( . ) Placement in INTERVAL Expression Between the YEAR and MONTH portions of the value. Between the DAY and HOUR portions of the value. Between the HOUR and MINUTE, and MINUTE and SECOND portions of the value. Between the SECOND and FRACTION portions of the value.

DATETIME and INTERVAL Values as Character Strings

You can enter DATETIME and INTERVAL data in the literal forms described in the previous sections or as quoted character strings. The following examples illustrate both formats:
CREATE TABLE mytable(mytime DATETIME YEAR TO DAY, myval INTERVAL DAY TO SECOND) INSERT INTO mytable(mytime) VALUES (DATETIME(89-5-12) YEAR TO DAY) INSERT INTO mytable(mytime) VALUES ("89-5-12") INSERT INTO mytable(myval) VALUES (INTERVAL(17 11:15:30) DAY TO SECOND) INSERT INTO mytable(myval) VALUES ("17 11:15:30")

Values that are specied as character strings are automatically converted into DATETIME or INTERVAL values. You can use character strings whenever you specify information for all elds dened for that DATETIME or INTERVAL column. When a character string is converted into a DATETIME or INTERVAL value, the engine assumes that the character string includes information about all the dened elds. You cannot use character strings to enter DATETIME or INTERVAL values for a subset of elds, because this produces ambiguous values. If the character string does not contain information for all elds, the engine returns an error. For example:
INSERT INTO mytable(mytime) VALUES (DATETIME(5-12) MONTH TO DAY) INSERT INTO mytable(mytime) VALUES ("5-12") INSERT INTO mytable(myval) VALUES (INTERVAL(11:15) HOUR TO MINUTE) INSERT INTO mytable(myval) VALUES ("11:15")

The previous DATETIME example (column mytime) enters a MONTH and DAY value into a column dened as YEAR TO DAY. Entering only these values is appropriate in the rst INSERT statement, because there you tell the engine that there is no YEAR information. In this case, the engine automatically adds

J-8

Working with DATETIME and INTERVAL Data

Operations on DATETIME and INTERVAL Values

the current year. The character string, however, does not indicate what information is omitted. The engine does not know whether the 5-12 refers to YEAR and MONTH, or MONTH and DAY, so it returns an error. The previous INTERVAL example (column myval) enters an HOUR and MINUTE value into a column dened as DAY TO SECOND. The rst INSERT statement simply pads the value with zeros for YEAR and SECOND. The second INSERT statement produces a conversion error, because the engine does not know whether the 11:15 refers to HOUR TO MINUTE or MINUTE TO SECOND.

Operations on DATETIME and INTERVAL Values

You can use DATETIME and INTERVAL data in a variety of arithmetic and Boolean expressions. You can manipulate a DATETIME value in conjunction with another DATETIME, a DATE, or an INTERVAL value, the current date and time (from the keyword CURRENT), the current date (TODAY), or some quantity of a specied unit of time (identied by the keyword UNITS). You can similarly manipulate an INTERVAL value. In addition, you can multiply or divide an INTERVAL value by a number. An INTERVAL column can hold a value that represents the difference between two DATETIME values, or the difference (or sum) of two INTERVAL values. In either case, the result is a span of time, which is an INTERVAL value. On the other hand, if you add or subtract an INTERVAL value from a DATETIME or DATE value, you get a DATETIME value, because the result is a specic point in time. The following table indicates the range of arithmetic expressions that you can use with DATETIME (or DATE) and INTERVAL data, along with the data type resulting from each expression.
Data Type of Operand 1 Datetime Datetime Interval Interval Datetime CURRENT Interval CURRENT Datetime Interval Interval Operator + or + + or + + or + or + or * or / Data Type of Operand 2 Datetime Interval Datetime Interval CURRENT Datetime CURRENT Interval UNITS UNITS Number Result Interval Datetime Datetime Interval Interval Interval Datetime Datetime Datetime Interval Interval

Working with DATETIME and INTERV Data AL

J-9

Manipulating DATETIME Values

You can substitute a DATE value for a DATETIME operand in this table to obtain a DATETIME or INTERVAL result, except that the difference between two DATE values is an INTEGER number of days. See the last section of this appendix for more information on using DATE values in expressions with DATETIME or INTERVAL values. No other combinations are allowed. You cannot add DATETIME or DATE values, because this operation does not produce either a point in time or a span of time. For example, you cannot add December 25 to January 1, though you can subtract it to nd the span between the two dates. Examples of valid DATETIME expressions are presented in the following sections.

Manipulating DATETIME Values

You can subtract most DATETIME values from each other. The result is either a positive or negative INTERVAL. The rst DATETIME value determines the eld precision for the result. If the second DATETIME value has fewer elds than the rst, the shorter value is automatically extended to match the longer one. If the second DATETIME value has more elds than the rst (regardless of whether the precision of the extra elds is larger or smaller than those in the rst value), the additional elds in the second value are ignored in the calculation.
DATETIME (1989-9-30 12:30) YEAR TO MINUTE - DATETIME (1989-8-1 11) YEAR TO HOUR result: INTERVAL (60 01:30) DAY TO MINUTE DATETIME (1989-9-30) YEAR TO DAY - DATETIME (10-1) MONTH TO DAY
result: INTERVAL (-1) DAY TO DAY [assuming current year is 1989]

In the rst example, no MINUTE eld is included for the second value, so the minutes are automatically set to zero, and the resulting INTERVAL is 60 days, 1 hour, and 30 minutes. In the second example, the year is not included for the second value. Therefore, the year is automatically set to the current year, in this case 1989, and the resulting INTERVAL is negative, to show that the second date is later than the rst.

J-10

Working with DATETIME and INTERVAL Data

Manipulating DATETIME with INTERVAL Values

Manipulating DATETIME with INTERVAL Values

INTERVAL values can be added to or subtracted from DATETIME or DATE values. The result is a DATETIME value. If you are adding an INTERVAL to a DATETIME or DATE, the order of values is unimportant. If you are subtracting, however, the DATETIME or DATE value must come rst. DATETIME (1989-8-1) YEAR TO DAY + INTERVAL (3-5) YEAR TO MONTH result: DATETIME (1993-01-01) YEAR TO DAY DATETIME (15:45) HOUR TO MINUTE - INTERVAL (720) MINUTE(3) TO MINUTE result: DATETIME (3:45) HOUR TO MINUTE

Adding or subtracting a non-zero INTERVAL value returns a DATETIME value that is earlier or later in time than the DATETIME or DATE operand in the expression. The rst example that follows moves the date ahead by three years and ve months. The second example moves the value back by 12 hours. This result, however, is presented as 720 minutes, a three-digit number. Since this precision exceeds the default of two digits, you must explicitly dene the rst qualier as MINUTE(3). In most situations, the database engine automatically adjusts the calculation when the initial values do not have the same precision. However, there are certain situations where you must explicitly adjust the precision of one value in order to perform the calculation. If the INTERVAL value that you are adding or subtracting includes any eld that is not included in the DATETIME or DATE value, you must explicitly use the EXTEND function to return an adjusted DATETIME value for the arithmetic operation. (For more information, see the description of EXTEND( ) near the end of Chapter 2.) For example, you cannot directly subtract the 720 minute INTERVAL in the second example from the DATETIME value in the rst example that has a precision from YEAR to DAY. You can perform this calculating by using the EXTEND function:
EXTEND (DATETIME (1989-8-1) YEAR TO DAY, YEAR TO MINUTE) - INTERVAL (720) MINUTE(3) TO MINUTE result: DATETIME (1989-07-31 12:00) YEAR TO MINUTE

The EXTEND function returns a DATETIME value whose precision is expanded from YEAR TO DAY to YEAR TO MINUTE. This allows the database engine to perform the calculation, and the result has the extended precision of YEAR to MINUTE from the rst operand.

Working with DATETIME and INTERV Data J-11 AL

Manipulating INTERVAL Values

The following examples use DATE values in expressions that evaluate to DATETIME values.
DEFINE calendar DATE LET calendar = "05/18/1990" calendar - INTERVAL (5-5) YEAR TO MONTH result: DATETIME (1984-12-18) YEAR TO DAY EXTEND(calendar, YEAR TO HOUR) - INTERVAL (4 8) DAY TO HOUR result: DATETIME (1990-05-13 16) YEAR TO HOUR

You cannot directly combine a DATE with an INTERVAL value whose last qualier is smaller than DAY. But as the previous example shows, you can use the EXTEND function to convert the value in a DATE column or variable to a DATETIME value that includes all the elds of the INTERVAL operand.

Manipulating INTERVAL Values

INTERVAL values can be added and subtracted from each other only if both

values are of similar precision. That is, both must be qualied in the range YEAR to MONTH, or else both must be in the range DAY to FRACTION. Within these ranges, the qualiers need not be identical.
INTERVAL (5-3) YEAR TO MONTH + INTERVAL (15) MONTH TO MONTH result: INTERVAL (6-06) YEAR TO MONTH INTERVAL (100:30.0005) MINUTE(3) TO FRACTION(4) - INTERVAL (120.01) SECOND(3) TO FRACTION result: INTERVAL (98:29.9905) MINUTE TO FRACTION(4)

In the rst example, a MONTH value is added to a YEAR TO MONTH value. The result (15 months) is automatically converted into years and months, resulting in a total INTERVAL value of 6 years and 6 months. In the second example, a SECOND TO FRACTION value is subtracted from a MINUTE TO FRACTION value. Note the use of numeric qualiers (in parentheses) to alert the engine that the MINUTE and FRACTION in the rst value and the SECOND in the second value exceed the default number of digits.

J-12

Working with DATETIME and INTERVAL Data

Operations Using CURRENT Values

Operations Using CURRENT Values

CURRENT is a keyword that evaluates to the current date and time. You can use it in place of a specic DATETIME value. The following examples of expressions with CURRENT assume that CURRENT is executed when the system clock returns a value equivalent to DATETIME (1989-8-1 00:00:00.000) YEAR TO FRACTION: DATETIME (1989-9-30 12:30) YEAR TO MINUTE - CURRENT result: INTERVAL (60 12:30) DAY TO MINUTE CURRENT - DATETIME (10-1) MONTH TO DAY result: INTERVAL (-61 00:00:00.000) DAY TO FRACTION CURRENT + INTERVAL (3-5) YEAR TO MONTH result: DATETIME (1993-01-01 00:00:00.000) YEAR TO FRACTION CURRENT - INTERVAL (720) MINUTE(3) TO MINUTE result: DATETIME (1989-07-31 12:00:00.000) YEAR TO FRACTION

The precision of the rst value determines the precision of output when using DATETIME values. In the rst example, the precision used for CURRENT matches the rst DATETIME value, YEAR TO MINUTE, so the resulting INTERVAL value has precision DAY TO MINUTE. The precision of the other three examples is determined by CURRENT, which uses the default precision of YEAR TO FRACTION. Similarly, you can specify the TODAY keyword in arithmetic expressions where a DATE value can appear.

Operations Using UNITS Values

A shorthand way to represent single-eld INTERVAL values is to use the UNITS keyword. It allows you to specify quickly amounts of a eld (for example, number of years) that you want to add to or subtract from a DATETIME or INTERVAL value. UNITS has the following syntax: number UNITS eld-name

Working with DATETIME and INTERV Data AL

J-13

Multiplying or Dividing INTERVAL Values

where number is the amount and eld-name is the type of eld. The following examples repeat previous examples, except UNITS replaces one of the INTERVAL values.
DATETIME (1989-8-1) YEAR TO DAY + 3 UNITS YEAR result: DATETIME (1992-08-01) YEAR TO DAY DATETIME (15:45) HOUR TO MINUTE - 720 UNITS MINUTE result: DATETIME (3:45)HOUR TO MINUTE INTERVAL (5-3) YEAR TO MONTH + 15 UNITS MONTH result: INTERVAL (6-06) YEAR TO MONTH
INTERVAL (100:30.0005) MINUTE(3) TO FRACTION(4) - 120 UNITS SECOND

result:

INTERVAL (98:30.0005) MINUTE TO FRACTION(4)

In each of these cases, an amount of a single eld is added to or subtracted from an INTERVAL or DATETIME value. Note that the second and third examples produce the same results as before. This is because manipulating singleeld INTERVAL values is identical to manipulating UNITS values of the same type and amount. The UNITS keyword is simply an easy way to write such INTERVAL values.

Multiplying or Dividing INTERVAL Values

You can multiply or divide INTERVAL values by a number. The number can be an integer or a fraction. However, INTERVAL values cannot be expressed as a fraction of a eld. All results are written only as integers. If there is a remainder from the calculation, it is ignored, and the result is truncated. Note the following examples:
INTERVAL (13-5) YEAR TO MONTH / 2 result: INTERVAL (6-8) YEAR TO MONTH INTERVAL (15:30.0002) MINUTE TO FRACTION(4) * 2.5 result: INTERVAL (38:45.0005) MINUTE TO FRACTION(4)

The results of any calculation include the same amount of precision as the original INTERVAL value. In the rst example, the YEAR value is divided by two leaving one year as a remainder. This remainder is converted into 12 months, added to the 5 existing months, and then divided. One month is left over, but there is no lower precision, so this remainder is simply discarded in the nal result of 6 years and 8 months.

J-14

Working with DATETIME and INTERVAL Data

Data Manipulation Statements

The second example multiplies an INTERVAL by a fraction. In this case, 15 * 2.5 = 37.5 minutes, 30 * 2.5 = 75 seconds, and 2 * 2.5 = 5 fraction(4). The .5 minute is converted into 30 seconds and 60 seconds are converted into 1 minute, which produces the nal result of 38 minutes, 45 seconds, and .0005 of a second.

Data Manipulation Statements

You can use DATETIME and INTERVAL values in any place that is appropriate for other data types. Frequently, you might use these values in the context of an SQL data manipulation statement, namely INSERT, UPDATE, DELETE, SELECT, LOAD, or UNLOAD. In a previous section, you saw how you can use DATETIME and INTERVAL values in an INSERT statement. The following examples illustrate how you can use these values in other types of SQL data manipulation statements.
CREATE TABLE mytable(mytime DATETIME YEAR TO DAY, myval INTERVAL DAY TO SECOND) UPDATE mytable SET myval = myval + INTERVAL (1 1:1:1) DAY TO SECOND DELETE FROM mytable WHERE mytime < CURRENT - 1 UNITS YEAR SELECT * FROM mytable WHERE mytime BETWEEN DATETIME(88-7-1) YEAR TO DAY and DATETIME (89-6-30) YEAR TO DAY SELECT mytime, mytime + INTERVAL (45) DAY TO DAY from mytable

The rst example updates all rows by a constant INTERVAL value. The second example deletes the rows that are more than a year old. The third example selects all rows for a given one-year period. The nal example includes a derived eld in the select-list so that you can compare the existing date with a later one.

DATETIME and DATE Compatibility

The database engine attempts to make appropriate data type conversions when they are required. For most situations, this allows you to use a DATETIME value wherever it is appropriate to use a DATE value and vice versa.

Working with DATETIME and INTERV Data AL

J-15

DATETIME and DATE Compatibility

You can use DATE values in arithmetic expressions with DATETIME or INTERVAL values. You can write expressions that allow the following manipulations:
DATE - DATETIME DATETIME - DATE DATE +/- INTERVAL result is INTERVAL result is INTERVAL result is DATETIME

In these cases, DATE values are rst converted to their corresponding DATETIME equivalents, and then the expression is computed in the normal way. In such expressions, you can also use TODAY, CURRENT, and UNITS to represent DATE, DATETIME, and INTERVAL values, respectively. Note: Expressions of the form DATE - DATE evaluate to a positive or negative INTEGER value, corresponding to the number of days between the two dates. If an INTERVAL value is required, you must perform the data type conversion explicitly with built-in functions. For example, the following expression uses the DATE( ) function to convert character string constants to DATE values, calculates their difference, and then uses the UNITS DAY keywords to convert the INTEGER result to an INTERVAL value:
(DATE("5/2/89") - DATE("4/6/54")) UNITS DAY result: INTERVAL (12810) DAY(5) TO DAY

If you need YEAR TO MONTH precision, you can use the EXTEND function on the rst DATE operand, as in the next example:
EXTEND(DATE("5/2/89"), YEAR TO MONTH) - DATE("4/6/54") result: INTERVAL (35-01) YEAR TO MONTH

While you can interchange DATE and DATETIME values in many situations, it must be clear whether a value is a DATE or a DATETIME. A DATE value can come from any of the following sources:

a column name or program variable of type DATE the TODAY keyword the DATE( ) function
A DATETIME value can come from any of the following sources:

a column name or program variable of type DATETIME the CURRENT keyword the EXTEND( ) function a DATETIME literal

J-16

Working with DATETIME and INTERVAL Data

DATETIME and DATE Compatibility

You can also represent DATE and DATETIME values as quoted character strings. You can only use strings that are in proper DATE or DATETIME format, however, and only in contexts where the corresponding data type of the string is known. The following examples illustrate what string format is required in various contexts:
DATE ("date-string") WHERE TODAY > "date-string" WHERE DATE-column < "date-string" EXTEND ("datetime-string" [, qualier]) WHERE DATETIME-column > "datetime-string"

When a DATE value is expected, the string must be in DATE format; when a DATETIME value is expected, the string must be in DATETIME format. For example, you can use the string "10/30/1989" as a date-string but not as a datetime-string. Instead, you must use "1989-10-30" or "89-10-30" as the datetime-string.

Working with DATETIME and INTERV Data AL

J-17

DATETIME and DATE Compatibility

J-18

Working with DATETIME and INTERVAL Data

Error Messages

Error Messages
This section contains the text of error messages that may appear when you work with INFORMIX-4GL and suggests corrective actions. All errors include an error number. Use the error number to quickly locate the message in this section. Error messages with negative numbers appear in order, starting with -100. The few error messages with positive numbers are placed at the back of the section. Note: Unless otherwise noted, the statement containing the error was not processed. -100 Description of Error: ISAM error: there is already a record with the same value in a unique key. Corrective Action: Check that you did not attempt to add a duplicate value to a column with a unique index via iswrite, isrewrite, isrewcurr, or isaddindex. -101 Description of Error: ISAM error: le is not open. Corrective Action: Check that the ISAM le has been opened using the isopen call, or that you have not tried to write to a ISAM le opened for read only. -102 Description of Error: ISAM error: illegal argument to ISAM function. Corrective Action: Check that one of the arguments to the ISAM call is not outside of the range of acceptable values for that argument.

-103

Description of Error: ISAM error: illegal key descriptor (too many parts or too long). Corrective Action: Check that one or more of the elements that make up the key description is not outside of the range of acceptable values for that element. (There is a maximum of 8 parts and 120 characters to each key descriptor.)

-104

Description of Error: ISAM error: too many les open. Corrective Action: The maximum number of les that can be open at one time would be exceeded if this request were processed. Reduce the number of open les by breaking your program up into two or more parts. The maximum number of open les per process is 20.

-105

Description of Error: ISAM error: bad ISAM le format. Corrective Action: The format of the ISAM le has been corrupted. Run the bcheck utility on the le, and it will try to repair damaged indexes. If bcheck cannot repair the le, you will need to reload your data from a backup medium.

-106

Description of Error: ISAM error: non-exclusive access. Corrective Action: You must rst open the le with exclusive access when you add or delete an index.

-107

Description of Error: ISAM error: record is locked. Corrective Action: The record or le requested by this call cannot be accessed because it has been locked by another user. Wait a moment and reenter your request. If you are certain that the table is not in use and your system uses tablename.lok les, you may need to empty the contents of this le. (This le contains information about which rows of the table are being used at any one time. It is normally emptied when a user nishes accessing the table. On occasion, the le is not emptied and, as a result, no one will be able to use the table.) You can copy the le /dev/null into this le to remove all locks on rows in the table. Contact your System Administrator about this action.

-108

Description of Error: ISAM error: key already exists. Corrective Action: You have attempted to add an index that previously has been dened. You will need to delete this existing index before dening another.

Error Messages

-109

Description of Error: ISAM error: the key is the les primary key. Corrective Action: An attempt was made to delete the primary key column. The primary key cannot be deleted by the isdelindex call.

-110

Description of Error: ISAM error: end or beginning of the le. Corrective Action: The beginning or end of the le was reached.

-111

Description of Error: ISAM error: no record found. Corrective Action: No record could be found that contained the requested value in the specied position. Edit your request and re-enter.

-112

Description of Error: ISAM error: there is no current record. Corrective Action: An attempt to access a record in the current list has been made, but there is no current list. You must rst perform a query and obtain a current list.

-113

Description of Error: ISAM error: the le is locked. Corrective Action: The table you wish to alter is currently being used by another user in exclusive mode. Wait until the table is no longer being used before entering your request. If you are certain that the table is not in use, you should run the UNLOCK TABLE command to unlock the table. Also, if your system contains tablename.lok les, you may need to empty the contents of this le. (This le contains information about which rows of the table are being used at any one time. It is normally emptied when a user nishes accessing the table. On occasion, the le is not emptied and, as a result, no one will be able to use the table.) You can copy the le /dev/null into this le to remove all locks on rows in the table. Be certain no processes are accessing the locked table before emptying the tablename.lok le. Contact your System Administrator about this action.

-114

Description of Error: ISAM error: the le name is too long. Corrective Action: Reduce the lename length to ten or fewer characters.

-116

Description of Error: ISAM error: cannot allocate memory. Corrective Action: Insufcient memory is available to run your request. (INFORMIX-4GL has run out of addressable data space.) You need to reduce the complexity of your statement or form.

Error Messages

-118

Description of Error: ISAM error: cannot read transaction log record. Corrective Action: The transaction log record is corrupted and cannot be used. You should CLOSE the DATABASE, execute a START DATABASE WITH LOG IN statement, and backup the database.

-119

Description of Error: ISAM error: bad log record. Corrective Action: The transaction log record is corrupted and cannot be used. You should CLOSE the DATABASE, execute a START DATABASE WITH LOG IN statement, and backup the database.

-120

Description of Error: ISAM error: cannot open log le. Corrective Action: Check that the log le exists, that you are using the correct pathname, and that you have operating system read and write permissions on the le.

-121

Description of Error: ISAM error: cannot write log le record. Corrective Action: Check that you have operating system write permission on the le and that sufcient disk space is available to add to the le.

-122

Description of Error: ISAM error: BEGIN WORK encountered in a database without transactions. Corrective Action: You can only use the BEGIN WORK statement in a database with transactions. Make sure that you have created or started the database with transactions.

-123

Description of Error: ISAM error: no shared memory. Corrective Action: Check that the Database Administrator has set up the shared memory partition.

-124

Description of Error: ISAM error: no BEGIN WORK found. Corrective Action: In a database that is not MODE ANSI, you must rst execute a BEGIN WORK statement before you can execute a COMMIT WORK or ROLLBACK WORK statement.

-125

Description of Error: ISAM error: cannot use NFS. Corrective Action: Do not attempt to access remote les on the network using NFS.

Error Messages

-126

Description of Error: ISAM error: bad row id Corrective Action: Run bcheck (on INFORMIX-SE) to check and repair index structures. Run tbcheck (on INFORMIX-OnLine) to check and repair index and data structures.

-127

Description of Error: ISAM error: no primary key. Corrective Action: Run bcheck to determine the source of the problem. Repair your table if necessary.

-128

Description of Error: ISAM error: no logging. Corrective Action: You have attempted to execute a statement that requires logging. Start your database with transactions and reexecute the statement.

-129

Description of Error: ISAM error: too many users. Corrective Action: The shared memory parameter for the maximum number of users was exceeded. Either ask your System Administrator to adjust the parameter, or try the statement again later.

-130

Description of Error: ISAM error: dbspace not found. Corrective Action: Check the name of your dbspace. Run the DB-Monitor to view existing dbspaces.

-131

Description of Error: ISAM error: no free disk space. Corrective Action: There is not enough contiguous disk space to complete the operation. Consult your System Administrator for assistance.

-132

Description of Error: ISAM error: the row size is too big. Corrective Action: Make the elds of the table smaller or create multiple tables with fewer elds.

-133

Description of Error: ISAM error: audit trail exists. Corrective Action: You cannot cluster a le with an audit trail. If you want to cluster the le, you must rst drop the audit trail.

-134

Description of Error: ISAM error: no more locks. Corrective Action: The shared memory parameter for the maximum number of locks was exceeded. Either lock the entire table, wait until more locks are available, or ask your System Administrator to adjust the parameter.

Error Messages

-135

Description of Error: ISAM error: tblspace does not exist Corrective Action: Check whether the tblspace number is correct. (INFORMIX-OnLine)

-136

Description of Error: ISAM error: no more extents Corrective Action: Use the DB-Monitor to add more disk space. (INFORMIX-OnLine)

-137

Description of Error: ISAM error: chunk table overow Corrective Action: There are too many chunks in the dbspace. Reinitialize INFORMIX-OnLine to allow for more chunks. (INFORMIX-OnLine)

-138

Description of Error: ISAM error: dbspace table overow Corrective Action: There are too many dbspaces. Reinitialize INFORMIX-OnLine to allow for more dbspaces. (INFORMIX-OnLine)

-139

Description of Error: ISAM error: logle table overow Corrective Action: There are too many logles. Reinitialize INFORMIX-OnLine to allow for more logles. (INFORMIX-OnLine)

-141

Description of Error: ISAM error: tblspace table overow Corrective Action: There are too many tblspaces currently in use. Wait and try later or reinitialize INFORMIX-OnLine to allow for more tblspaces. (INFORMIX-OnLine)

-142

Description of Error: ISAM error: overow of tblspace page Corrective Action: The keys for the table are too large for a page. Reduce the size of the indexes. (INFORMIX-OnLine)

-143

Description of Error: ISAM error: deadlock detected Corrective Action: A deadlock has occurred. Rollback the current transaction and retry it.

-144

Description of Error: ISAM error: key value locked Corrective Action: Wait and retry action. (INFORMIX-OnLine)

-145

Description of Error: ISAM error: system does not have disk mirroring Corrective Action: If you are trying to mirror a dbspace, rst reinitialize INFORMIX-OnLine with a mirror for the root dbspace, then mirror other dbspaces. (INFORMIX-OnLine)

Error Messages

-146

Description of Error: ISAM error: the other copy of this disk is currently disabled or non-existent. Corrective Action: Bring up the other chunk of the mirror pair before you bring down this chunk. (INFORMIX-OnLine)

-147

Description of Error: ISAM error: archive in progress. Corrective Action: Check that the action you are taking is compatible with archiving. You cannot add a log or mirror a dbspace which contains a log if an archive is in progress. (INFORMIX-OnLine)

-148

Description of Error: ISAM error: dbspace is not empty Corrective Action: Drop all tables from a dbspace before trying to remove it. (INFORMIX-OnLine)

-149

Description of Error: ISAM error: INFORMIX-OnLine daemon is no longer running (INFORMIX-OnLine) Corrective Action: You may have killed the OnLine daemon by accidentally killing the wrong process. You must reinitialize INFORMIX-OnLine.

-200

Description of Error: Identier is too long. Corrective Action: Identiers must be 18 characters or less. Select a new identier of the appropriate length.

-201

Description of Error: A syntax error has occurred. Corrective Action: Check that you have not misspelled an SQL statement, placed key words out of sequence, or included an INFORMIX-4GL reserved word in your query.

-202

Description of Error: An illegal character has been found in the statement. Corrective Action: Remove the illegal character (often a non-printable control character) and resubmit the statement.

-203

Description of Error: An illegal integer has been found in the statement. Corrective Action: Integers must be whole numbers from -2,147,483,647 to 2,147,483,647. Check that you have not included a number with a fractional portion or a number outside of the range of acceptable whole numbers. Check also that you have not inadvertently entered a letter in place of a number (for example, 125p3 instead of 12503).

Error Messages

-204

Description of Error: An illegal oating-point number has been found in the statement. Corrective Action: Check that you have not inadvertently entered a letter in place of a number (for example, 125b3 in place of 12503).

-205

Description of Error: Cannot use ROWID for views. Corrective Action: Restructure your statement so that the virtual column is not used in dening the view.

-206

Description of Error: The specied table name is not in the database. Corrective Action: Check the spelling of the table name in your statement. Check the systables system catalog for a list of all database tables.

-207

Description of Error: Cannot update cursor declared on more than one table. Corrective Action: Check that you have not attempted to use a FOR UPDATE clause with cursors on multiple tables. Restructure your update statement, perhaps using multiple cursors.

-208

Description of Error: Memory allocation failed during query processing. Corrective Action: Reduce the complexity of your query or program.

-209

Description of Error: Incompatible database format. Corrective Action: You are attempting to use INFORMIX-4GL with a database built by INFORMIX-SQL or INFORMIX-ESQL/C 1.1. You must rst run dbupdate on your database, which will prepare the database for INFORMIX-4GL.

-210

Description of Error: Pathname too long. Corrective Action: INFORMIX-4GL will accept a pathname of up to 70 total characters. Reduce the length of the pathname.

Error Messages

-211

Description of Error: Cannot read system catalog catalog-name. System Action: See below for a list of system actions. Corrective Action: Check the ISAM error for information about the source of the problem. Depending upon the content of the statement and the system catalog cited in the error message, the following actions have occurred: For a CREATE TABLE statement: the systabauth catalog was not read, the table was created, but no authorizations are granted to PUBLIC. For a DROP TABLE statement: if the systables catalog was not read, then no action was taken; if the sysviews catalog was not read, then the table was dropped, but any views built on the table might not have been dropped. For a DROP VIEW statement: the sysviews catalog was not read, and no action was taken. For a DROP INDEX statement: the sysindexes or systables catalogs was not read, and the index was not dropped. For a DROP SYNONYM statement: the systables catalog was not read (for tabtype = S), and the synonym was not dropped. For a DROP DATABASE statement: the systables catalog was not read, and the database was not dropped. For a START DATABASE statement: the systables catalog was not read, and the database was not started. For a DATABASE statement: the systables or sysusers catalog was not read, and the database was not selected.

-212

Description of Error: Cannot add index. Corrective Action: Check the ISAM error for information about the source of the problem.

-213

Description of Error: Statement interrupted by user. Corrective Action: INFORMIX-4GL has received an interrupt signal (probably due to the user pressing the DEL or CTRL-C key). Resubmit your statement.

Error Messages

-214

Description of Error: Cannot remove le for table tablename. System Action: If this is a DROP DATABASE statement, then some tables may have been dropped from the database. If this is a DROP TABLE statement, then some system entries for the table may have been dropped from the database. Corrective Action: INFORMIX-4GL cannot remove one or more of the entries in the system catalogs for the table. Check the ISAM error for information about the source of the problem. Check with the System Administrator about remedial actions.

-215

Description of Error: Cannot open le for table tablename. Corrective Action: Check the ISAM error for information about the source of the problem.

-216

Description of Error: Cannot remove ISAM index on le. Corrective Action: Check the ISAM error for information about the source of the problem.

-217

Description of Error: Column column-name not found in any table in the query. Corrective Action: Correct the spelling of the column name or that columnname exists in database table. Check for the presence of required commas and quotes.

-218

Description of Error: Synonym name not found. Corrective Action: Check the spelling of the synonym. If needed, check the systables system catalog (where tabtype = S) for a list of the current synonyms for table names.

-219

Description of Error: Wildcard matching cannot be used with non-character types. Corrective Action: Wildcards ( *, ?) and characters enclosed in brackets [ ] can be used only with CHAR data types. Check the data type for the offending column.

-220

Description of Error: There is no FROM clause in the query. Corrective Action: Must include a FROM clause in the query. Check that you do not have an illegal character ($, #, &, etc., or a CONTROL character) in the line prior to the FROM keyword.

10

Error Messages

-221

Description of Error: Cannot build temporary le for new table table-name. Corrective Action: ISAM cannot access the temporary directory (usually, /tmp) or the disk may be out of space. Check the ISAM error for information about the source of the problem.

-222

Description of Error: Cannot write to temporary le for new table tablename. Corrective Action: The disk may be out of space. Check the ISAM error for information about the source of the problem.

-223 -224

Description of Error: Duplicate table name table-name in the FROM clause. Use an alias to rename one of the tables. Description of Error: Cannot open log le. Corrective Action: Check the ISAM error for information about the source of the problem.

-225

Description of Error: Cannot create le for system catalog catalog-name. System Action: The CREATE DATABASE statement was not completed. Some system catalogs may have been created. Corrective Action: Check the ISAM error for information about the source of the problem.

-226

Description of Error: Cannot create index for system catalog catalog-name. System Action: The CREATE DATABASE statement was not completed. Some system catalogs may have been created. Corrective Action: Check the ISAM error for information about the source of the problem.

-227

Description of Error: Cannot use ORDER BY clause when selecting into temporary table. Corrective Action: Remove the ORDER BY clause from your statement. Place an index on the column you wish to order by after creating the temporary table.

-228

Description of Error: Cannot have negative characters. Corrective Action: Check that you have not included a negative CHAR data type (for example, a -a or -p) in your statement.

Error Messages 11

-229

Description of Error: Could not open or create a temporary le. Corrective Action: Check the ISAM error for information about the source of the problem.

-230

Description of Error: Could not read a temporary le. Corrective Action: Check the ISAM error for information about the source of the problem.

-231

Description of Error: Cannot perform aggregate function with distinct on expression. Corrective Action: Select the expression into a temporary table and then perform an aggregate distinct on the temporary table.

-232

Description of Error: A SERIAL column column-name cannot be updated. Corrective Action: The values appearing in a SERIAL column are provided by INFORMIX-4GL and cannot be updated.

-233

Description of Error: Cannot read record that is locked by another user. Corrective Action: Another user has locked the record. Wait a moment and re-enter your request.

-234

Description of Error: Cannot insert into virtual column column-name. Corrective Action: The specied column is derived from an expression or an aggregate function. Redene the view.

-235

Description of Error: Character column size is too big. Corrective Action: Redene the size of the column to 32,511 characters or less.

-236

Description of Error: Number of columns in INSERT does not match number of VALUES. Corrective Action: Check that the number of columns in the table or in the column list matches the number of values in the VALUES clause or the SELECT clause.

-237

Description of Error: Cannot begin work. Corrective Action: Check the ISAM error number for information about the source of the problem. Contact your System Administrator or Database Administrator if you need assistance with interpreting the ISAM error number.

12

Error Messages

-238

Description of Error: Cannot COMMIT WORK. Corrective Action: Your log le might be corrupted. Check the ISAM error number for information about the source of the problem. Contact your System Administrator or Database Administrator if you need assistance with interpreting the ISAM error number.

-239

Description of Error: Could not insert new rowduplicate value in a UNIQUE INDEX column. Corrective Action: The row contains a value which already exists in the column (indexed as unique) of an existing row. Enter a new value for the column or remove the unique index on the column.

-240

Description of Error: Could not delete a row. Corrective Action: Check the ISAM error for information about the source of the problem.

-241

Description of Error: Cannot ROLLBACK WORK. Corrective Action: Check the ISAM error number for information about the source of the problem. Contact your System Administrator or Database Administrator if you need assistance interpreting the ISAM error number.

-242

Description of Error: Could not open database table table-name. Corrective Action: Check the ISAM error for information about the source of the problem.

-243

Description of Error: Could not position within a table table-name. Corrective Action: Check the ISAM error for information about the source of the problem.

-244

Description of Error: Could not do a physical-order read to fetch next row. Corrective Action: Check the ISAM error for information about the source of the problem.

-245

Description of Error: Could not position within a le via an index. Corrective Action: Check the ISAM error for information about the source of the problem.

-246

Description of Error: Could not do an indexed read to get the next row. Corrective Action: Check the ISAM error for information about the source of the problem.

Error Messages

13

-247

Description of Error: ROLLFORWARD database failed. Corrective Action: Check the ISAM error for information about the source of the problem. Contact your System Administrator or Database Administrator if you need assistance with interpreting the meaning of the ISAM error.

-248

Description of Error: Value of the program variable in the WHERE clause is NULL. Corrective Action: Use IS [NOT] NULL for NULL operation or initialize the program variable.

-249

Description of Error: Virtual column must have explicit name. Corrective Action: When selecting into a temporary table or creating a view, each temporary or view column based on an expression must be given a unique name. Check also that distinct names are provided.

-250

Description of Error: Cannot read record from le for update. Corrective Action: The record might be locked by another user. Check the ISAM error for information about the source of the problem.

-251

Description of Error: ORDER BY column number too big. Corrective Action: The number of the column noted in your ORDER BY statement exceeds the total number of columns in the SELECT statement.

-252

Description of Error: Cannot get system information for table. System Action: Some statistics might be updated. Corrective Action: Check the ISAM error for information about the source of the problem.

-253

Description of Error: Identier too longmaximum length is 18. Corrective Action: Check the spelling or length of the table name.

-254

Description of Error: Too many or too few host variables given. Corrective Action: Check that the number of program variables in the fetch is equal to the number used when dening the cursor.

-255

Description of Error: Not in transaction. Corrective Action: The statement must be executed within a transaction. First start a transaction, then perform the statement.

14

Error Messages

-256

Description of Error: Transaction not available. Corrective Action: INFORMIX-4GL cannot perform a transaction operation (BEGIN WORK, ROLLBACK WORK, COMMIT WORK) on the database because a transaction log was never created for the database. Ask your Database Administrator to create a transaction log for the database.

-257

Description of Error: System limit on cursors exceeded, maximum is num. Corrective Action: Reduce the number of cursors used in the program.

-258

Description of Error: System errorinvalid statement ID received by the sqlexec process. Corrective Action: Make sure that the cursor or object is dened after the
DATABASE statement. Contact the Informix Technical Support Department if

you need additional assistance. -259 Description of Error: Cursor not open. Corrective Action: First open a cursor, then attempt the fetch. -260 Description of Error: Cannot execute a SELECT statement that is PREPAREDmust use cursor. Corrective Action: Use a cursor for the SELECT statement. -261 Description of Error: Could not create le for table table. Corrective Action: Check the ISAM error for information about the source of the problem. -262 Description of Error: There is no current cursor. Corrective Action: You cannot perform an UPDATE or DELETE action when no current row exists. First perform a fetch, then attempt this action. -263 Description of Error: Could not lock row for UPDATE. Corrective Action: Check the ISAM error for information about the source of the problem. -264 Description of Error: Could not write to a temporary le. Corrective Action: Check the ISAM error for information about the source of the problem.

Error Messages

15

-265

Description of Error: Load or insert cursors must be run within a transaction. Corrective Action: On databases with transactions, you must execute a BEGIN WORK statement before using an insert cursor.

-266

Description of Error: There is no current row for UPDATE/DELETE cursor. Corrective Action: You cannot perform an UPDATE or DELETE action when no current row exists. First perform a fetch, then attempt this action.

-267

Description of Error: The cursor has been previously released and is unavailable. Corrective Action: Make sure that the cursor is open before you make reference to it.

-268

Description of Error: Cannot use SELECT DISTINCT with UNION ALL. Corrective Action: Rewrite your statement.

-269

Description of Error: Cannot add column column-name that does not accept nulls. Corrective Action: Rewrite your statement.

-270

Description of Error: Could not position within a temporary le. Corrective Action: Check the ISAM error for information about the source of the problem.

-271

Description of Error: Could not insert new row into the table. Corrective Action: Check the ISAM error for information about the source of the problem.

-272

Description of Error: No SELECT permission. Corrective Action: Request permission to SELECT from the owner of the table.

-273

Description of Error: No UPDATE permission. Corrective Action: Request permission to UPDATE from the owner of the table.

-274

Description of Error: No DELETE permission. Corrective Action: Request permission to DELETE from the owner of the table.

16

Error Messages

-275

Description of Error: No INSERT permission. Corrective Action: Request permission to INSERT from the owner of the table.

-276

Description of Error: Cursor not found. Corrective Action: You have called for a cursor that has not been declared in the current session. (The current session runs from the issuance of a DATABASE statement to a CLOSE DATABASE statement, or the issuance of the next DATABASE statement.) Declare your cursor within the current (database) session.

-277

Description of Error: UPDATE table table-name is not the same as the cursor table. Corrective Action: Either declare a cursor on the table used in the UPDATE statement, or update the table used in the cursor. Check the spelling of the table name and cursor name.

-278

Description of Error: Too many ORDER BY columns. Corrective Action: Reduce the number of columns included in the ORDER BY clause to 8 or less.

-279

Description of Error: Cannot GRANT or REVOKE database privileges for table or view. Corrective Action: Database privileges (CONNECT, RESOURCE, and DBA) cannot be granted on individual tables.

-280

Description of Error: A quoted string exceeds 256 bytes. Corrective Action: Reduce the string to fewer than 256 characters.

-281

Description of Error: Could not add index to a temporary table. Corrective Action: Check the ISAM error for information about the source of the problem.

-282

Description of Error: Found a quote for which there is no matching quote. Corrective Action: Check that all quoted strings are properly terminated with a quote.

-283

Description of Error: Found a non-terminated comment ({ with no matching }). Corrective Action: Check that all comments are properly enclosed in braces. (Comments cannot be nested.)
Error Messages 17

-284

Description of Error: A subquery has returned not exactly one row. Corrective Action: Restructure the subquery by adding more components to the WHERE clause so that only one row is returned.

-285

Description of Error: Invalid cursor received by sqlexec. Corrective Action: First issue a PREPARE statement within the current session, then re-enter your original statement.

-286

Description of Error: An expression cannot include ANY or ALL. Corrective Action: ANY and ALL can only be used in association with a subquery.

-287

Description of Error: Cannot add SERIAL column column-name to the table. Corrective Action: A SERIAL column does not accept NULL values. Add the column to the table as type INTEGER, UPDATE it so that there are no NULLS, and then MODIFY it to type SERIAL.

-288

Description of Error: Table table-name not locked by current user. Corrective Action: You cannot unlock a table locked by another user. Only the user who locked the table (or the DBA) can unlock the table.

-289

Description of Error: Cannot lock table table-name in share mode. Corrective Action: The table is already locked in exclusive mode. Wait until the table is unlocked before reexecuting your request.

-290

Description of Error: Cursor not declared with FOR UPDATE clause. Corrective Action: You must rst declare a cursor with FOR UPDATE if the cursor is used for updating the database.

-291

Description of Error: Table table-name is already locked. Corrective Action: You must rst unlock the table before executing your request.

-292

Description of Error: An implied INSERT column column-name does not accept NULLs. Corrective Action: INFORMIX-4GL will not allow you to insert a NULL value in a column that does not allow NULLS. Check to see if a non-NULL column is included in the column list in the INSERT statement.

18

Error Messages

-293

Description of Error: IS [NOT] NULL predicate may be used only with simple columns. Corrective Action: Restructure your query.

-294

Description of Error: The column column-name must be in the GROUP BY list. Corrective Action: All non-aggregate columns in the SELECT list must be included in the GROUP BY list. Restructure your statement to include all columns that are not aggregate functions.

-295

Description of Error: The GROUP BY column number is too large. Corrective Action: The number of the column noted in your GROUP BY statement exceeds the total number of columns in the SELECT statement.

-297

Description of Error: The SELECT list may not contain a subquery. Corrective Action: Remove the subquery from the SELECT list in the statement.

-298

Description of Error: COUNT( [DISTINCT] colname ) may be used only with a simple column. Corrective Action: You cannot include expressions within the COUNT([DISTINCT] ... ) function. Restructure the query.

-299

Description of Error: A query may not contain more than one DISTINCT. Corrective Action: Restructure your query to include only one DISTINCT.

-300

Description of Error: There are too many GROUP BY columns. Corrective Action: The maximum number of columns in a GROUP BY clause is 8. Reduce the number of columns in the statement to 8 or less.

-301

Description of Error: The total size of the GROUP BY columns is too big. Corrective Action: The total number of characters in all columns listed in the GROUP BY list exceeds 120 characters. Reduce the column list.

-302

Description of Error: No GRANT option or illegal option on multi-table view. Corrective Action: You do not have permission to grant access privileges to the table. Only the table owner, DBA, or a user with GRANT permission can do this.

Error Messages

19

-303

Description of Error: Expression mixes columns with aggregates. Corrective Action: Restructure your query so that columns and aggregates are not included in the same expression.

-304

Description of Error: HAVING can only have expressions with aggregates or columns in GROUP BY clause. Corrective Action: Make sure that your HAVING clause contains either columns that are in the GROUP BY clause or expressions with aggregates.

-305

Description of Error: Subscripted column column-name is not of type CHAR, VARCHAR, TEXT nor BYTES. Corrective Action: Verify that all subscripted columns are of type CHAR,
VARCHAR, TEXT, or BYTE.

-306

Description of Error: Subscript out of range. Corrective Action: The range of the subscript delimiter exceeds the range of the column data type. Check the size of the data type and reduce the subscript range.

-307

Description of Error: Illegal subscript denition. Corrective Action: Check that you have not reversed the order of the subscript delimiters ([3,8] is a valid subscript; [8,3] is invalid) or included a negative number as a subscript delimiter.

-308

Description of Error: Column type must be the same for each UNION statement. Corrective Action: Check that each column in the UNION statement is of the same data type.

-309

Description of Error: ORDER BY column column-name must be in SELECT list. Corrective Action: Check that columns included in the ORDER BY clause appear in the SELECT list.

-310

Description of Error: Table table-name already exists in database. Corrective Action: Select an alternate name for the table.

-311

Description of Error: Cannot open system catalog catalog-name. Corrective Action: Check the ISAM error for information about the source of the problem.

20

Error Messages

-312

Description of Error: Cannot update system catalog catalog-name. Corrective Action: Check the ISAM error for information about the source of the problem.

-313

Description of Error: Not owner of table table-name. Corrective Action: Only the owner of the table (or the Database Administrator) can remove the table.

-314

Description of Error: Table table-name currently in use. Corrective Action: The table you wish to drop is currently being used by another user. Wait until the table is no longer being used before executing your request.

-315

Description of Error: No CREATE INDEX permission. Corrective Action: Permission not granted for you to create an index on the table.

-316

Description of Error: Index index-name already exists in database. Corrective Action: An index currently exists for the table. You must drop the existing index before creating a new one.

-317

Description of Error: Must have the same number of selected columns in each UNION statement. Corrective Action: Check the number of columns selected in each SELECT statement.

-318

Description of Error: File with the same name as specied log le already exists. Corrective Action: Select a different name for the log le.

-319

Description of Error: Index does not exist in database le. Corrective Action: Check the spelling of the index name or check the sysindexes system catalog for the correct index name.

-320

Description of Error: Not owner of index index-name. Corrective Action: Only the owner of the index (or the Database Administrator) can remove the index.

-321

Description of Error: Cannot group by aggregate column. Corrective Action: Check the column number used in the GROUP BY clause.

Error Messages

21

-322

Description of Error: Cannot alter view view-name. Corrective Action: Views cannot be altered. You must drop and then recreate the view.

-323

Description of Error: Cannot grant permission on temporary table. Corrective Action: Permissions can only be granted on permanent tables.

-324

Description of Error: Ambiguous column column-name. Corrective Action: A column name exists in more than one table cited in your query. Prex each column name with the appropriate table name.

-325

Description of Error: Log le must be given a full pathname starting with a /. Corrective Action: Provide the full pathname for the log le.

-326

Description of Error: Expecting CHAR type host variable. Corrective Action: The cursor is on a CHAR column and your program is attempting to pass it a non-CHAR data type. Restructure your statement.

-327

Description of Error: Cannot unlock table tablename within a transaction. Corrective Action: You cannot execute an UNLOCK TABLE statement within a transaction.

-328

Description of Error: Column column-name already exists in table. Corrective Action: Select a new column name for the column.

-329

Description of Error: Database not found or no system permission. Corrective Action: Check the spelling of the database name. Check that the database name exists in your current directory or a directory included in your DBPATH environment variable. Check the ISAM error for information about the source of the problem.

-330

Description of Error: Cannot create database. Corrective Action: Check that you have not entered the name of an existing database. Select an alternate name for the database. Check the ISAM error for information about the source of the problem.

22

Error Messages

-331

Description of Error: Cannot drop database directory. System Action: All database les in the database directory are deleted, but the directory remains. Corrective Action: Remove any non-database les present in the database directory, then remove the directory. Check the ISAM error for information about the source of the problem.

-332

Description of Error: Cannot access audit trail name information. Corrective Action: Re-execute your request. If you again receive the error, the audit trail le has been corrupted. You may need to drop and restart the audit trail.

-333

Description of Error: The audit trail le already exists with a different name. Corrective Action: You must rst drop the existing audit trail le (issue a DROP AUDIT statement) before creating a new audit trail.

-334

Description of Error: Cannot create audit trail. Corrective Action: You must indicate the full pathname of the le receiving the audit trail. Check that you have permission to write to a le in the selected directory. Contact your System Administrator if you need help with this action.

-335

Description of Error: There is no audit trail for the specied table. Corrective Action: INFORMIX-4GL is unable to recover the table as no audit trail was created.

-336

Description of Error: Cannot create or drop audit on temporary table table-name. Corrective Action: You cannot place an audit trail on a temporary table.

-337

Description of Error: Cannot create view on temporary table table-name. Corrective Action: You cannot create a view on a temporary table.

-338

Description of Error: Cannot drop audit trail. Corrective Action: Re-execute your request. If the problem reoccurs, check the ISAM error message for information about the source of the problem. Contact your System Administrator if you require assistance with this action.

Error Messages

23

-339

Description of Error: The audit trail le name must be given in full directory path. Corrective Action: Edit your statement to include the full pathname of the audit trail le.

-340

Description of Error: Cannot open audit trail le. (operating system error). Corrective Action: Check that you have operating system read permission to the le. Contact your System Administrator if you need help with this action.

-341

Description of Error: Could not read a row from audit trail le. Corrective Action: The request was not completed (possible operating system error). Re-execute your request. If the problem reoccurs, check the ISAM error message for information about the source of the problem. Contact your System Administrator if you require assistance with this action. If you again receive the error, the audit trail le has been corrupted. You may need to drop and restart the audit trail.

-343

Description of Error: Row from audit trail was added to a different position than expected. Corrective Action: Re-execute your request. If the problem reoccurs, check the ISAM error message for information about the source of the problem. Contact your System Administrator if you require assistance with this action. If you again receive the error, the audit trail le has been corrupted. You may need to drop and restart the audit trail.

-344

Description of Error: Cannot delete rowrow in table does not match row in audit trail. Corrective Action: Re-execute your request. If the problem reoccurs, check the ISAM error message for information about the source of the problem. Contact your System Administrator if you require assistance with this action. If you again receive the error, the audit trail le has been corrupted. You may need to drop and restart the audit trail.

-345

Description of Error: Cannot update rowrow in table does not match row in audit trail. Corrective Action: Re-execute your request. If the problem reoccurs, check the ISAM error message for information about the source of the problem. Contact your System Administrator if you require assistance with this action. If you again receive the error, the audit trail le has been corrupted. You may need to drop and restart the audit trail.

24

Error Messages

-346

Description of Error: Could not update a row in the table. Corrective Action: Check the ISAM error for information about the source of the problem.

-347

Description of Error: Could not open table for exclusive access. Corrective Action: Check the ISAM error for information about the source of the problem.

-348

Description of Error: Could not read a row from the table. Corrective Action: Check the ISAM error for information about the source of the problem.

-349

Description of Error: Database not selected yet. Corrective Action: You must rst select the database before executing a statement that refers to a database.

-350

Description of Error: Index already exists on column. Corrective Action: Adding an index on the column is not necessary, as the column is already indexed.

-351

Description of Error: Database contains tables owned by other users. Corrective Action: You can only drop a database if you own all tables in the database or have Database Administrator status. Contact your Database Administrator if you need help with this action.

-352

Description of Error: Column not found. Corrective Action: Check the spelling of the column name.

-353

Description of Error: No table or view specied when granting or revoking table privileges. Corrective Action: You must include the name of the table or view on which a privilege is granted or revoked in your SQL statement.

-354

Description of Error: Incorrect database or cursor name format. Corrective Action: A database name must be ten characters or less. A cursor name must be 18 characters or less. A database or cursor name must begin with a letter, and contain letters, numbers, or underscores. Check that you have not included an illegal character in the name.

Error Messages

25

-355

Description of Error: Cannot rename le for table. Corrective Action: Check the ISAM error for information about the source of the problem.

-356

Description of Error: Table table-name specied in both main query and subquery. Corrective Action: The statement is ambiguous because a column cannot be identied uniquely. Use an alias to rename the offending table.

-357

Description of Error: Dependent table for view view-name has been altered. Corrective Action: A table upon which the view is constructed has been modied (for example, a column has been dropped, a data type has been modied, or a column has been added to the middle of the table). Drop the view and create a new view.

-358

Description of Error: You must close the current database before you execute CREATE, START, or ROLLFORWARD. Corrective Action: You can only use the CREATE DATABASE, START DATABASE, and ROLLFORWARD DATABASE statements when there is no current database. Execute a CLOSE DATABASE statement before executing one of these statements.

-359

Description of Error: Cannot drop current database. Corrective Action: First execute a CLOSE DATABASE statement before executing a DROP DATABASE statement.

-360

Description of Error: Cannot modify table or view used in subquery. Corrective Action: If allowed, your statement could reduce to a looping program. Edit your statement.

-361

Description of Error: Column size too large. Corrective Action: Reduce the size of the column. You cannot have a CHAR column larger than 32,511 characters.

-362

Description of Error: Can have only one column of SERIAL type. Corrective Action: You cannot have more than one column of SERIAL type in a table. Select an alternate data type for the column.

-363

Description of Error: Cursor not on SELECT statement. Corrective Action: Use EXECUTE to execute prepared objects on non-SELECT statements.

26

Error Messages

-364

Description of Error: Column column-name not declared FOR UPDATE OF. Corrective Action: Include the column in the FOR UPDATE OF list.

-365

Description of Error: Cursor must be on simple SELECT for FOR UPDATE. Corrective Action: Check that the cursor does not include more than one table or involve aggregates.

-366

Description of Error: The scale exceeds the maximum precision specied. Corrective Action: The problem is located in a DECIMAL or MONEY column. The scale (number of digits to the right of the decimal point) exceeds the precision (total number of digits). You must correct one of the following conditions:
DECIMAL ( m, n) MONEY ( m, n) MONEY ( m) where n > m where n > m where m < 2

-367

Description of Error: Sums and averages cannot be computed for character columns. Corrective Action: Check that you have not included a column of a character data type in the aggregate function statement.

-368

Description of Error: Incompatible sqlexec module. Corrective Action: Check that the correct version of sqlexec has been installed. Contact your Database Administrator if you need help with this action.

-369

Description of Error: Invalid serial number. Please consult your installation instructions. Corrective Action: Check that the correct version of sqlexec has been installed. Contact your Database Administrator if you need help with this action.

-370

Description of Error: Cannot drop last column. Corrective Action: Only one column remains in the table. Use the DROP TABLE statement to remove the table.

-371

Description of Error: Cannot create unique index on column with duplicate data. Corrective Action: The column contains duplicate data.

Error Messages

27

-372

Description of Error: Cannot alter table with audit trail on. Corrective Action: You must rst drop the audit trail before making any changes to the table. After making the changes, you may want to re-establish an audit trail.

-373

Description of Error: DBPATH too long. Corrective Action: Reduce the length of your DBPATH environment variable.

-374

Description of Error: Can only use column number in ORDER BY clause with UNION. Corrective Action: Restructure the query, using ordinal numbers for the ORDER BY columns.

-375

Description of Error: Cannot create log le for transaction. Corrective Action: Check the ISAM error for information about the source of the problem.

-376

Description of Error: Log le already exists. Corrective Action: Select an alternate name for the log le.

-377

Description of Error: Must terminate transaction before closing database. Corrective Action: Issue a COMMIT WORK or ROLLBACK statement before closing the database.

-378

Description of Error: Record currently locked by another user. Corrective Action: Wait until the record is unlocked before submitting the statement. Check the ISAM error for information about the source of the problem.

-379

Description of Error: Cannot revoke privilege on columns. Corrective Action: First revoke UPDATE or SELECT privilege on the table, then grant the revoked privileges.

-380

Description of Error: Cannot erase log le. Corrective Action: Check the ISAM error for information about the source of the problem.

28

Error Messages

-381

Description of Error: Cannot grant to someone who has granted you the same privilege before. Corrective Action: The name of the individual who granted you permission to use the table must be removed from your user list.

-382

Description of Error: Same number of columns must be specied for view and select clause. Corrective Action: Check the number of columns in the view denition and the selected columns.

-383

Description of Error: View column for aggregate or expression must be explicitly named. Corrective Action: Provide a name for all virtual columns.

-384

Description of Error: Cannot modify non-simple view. Corrective Action: Can only modify views built on a single table.

-385

Description of Error: Data value out of range. Corrective Action: Check the view denition for valid data ranges.

-386

Description of Error: Column contains null values. Corrective Action: The table contains NULL values in a column being altered to disallow NULLS. Remove NULL values from the column.

-387

Description of Error: No connect permission. Corrective Action: Contact the Database Administrator and request CONNECT permission.

-388

Description of Error: No resource permission. Corrective Action: Contact the Database Administrator and request RESOURCE permission.

-389

Description of Error: No DBA permission. Corrective Action: Contact the Database Administrator and request DBA permission.

-390

Description of Error: Synonym already used as table name or synonym. Corrective Action: Select a different synonym that does not match the name or synonym of any table or view in the current database. Check the systables system catalog (where tabtype = S) for a list of existing synonyms.

Error Messages

29

-391

Description of Error: Cannot insert a NULL into column column-name. Corrective Action: Check that a column that does not allow NULL values is omitted from the insert column list.

-392

Description of Error: System errorunexpected NULL pointer encountered. Corrective Action: Notify the Informix Technical Support Department.

-393

Description of Error: A condition in the where clause results in a two-sided outer join. Corrective Action: A two-sided outer join is not allowed. Restructure your query.

-394

Description of Error: View view-name not found. Corrective Action: Check the spelling of the view name. Check the sysviews system catalog for a list of existing views.

-395

Description of Error: The where clause contains an outer cartesian product. Corrective Action: Check the syntax of the statement.

-396

Description of Error: Illegal join between a nested outer table and a preserved table. Corrective Action: Check the syntax of the statement.

-397

Description of Error: System catalog corrupted. Corrective Action: Contact the Database Administrator for help with this error.

-398

Description of Error: Cursor manipulation must be within a transaction. Corrective Action: Perform a BEGIN WORK statement before any cursor manipulations.

-399

Description of Error: Cannot access log le. Corrective Action: You cannot edit the log le.

-400

Description of Error: Fetch attempted on unopen cursor. Corrective Action: Check that the cursor was properly opened using an OPEN CURSOR statement.

-401

Description of Error: Fetch attempted on NULL cursor. Corrective Action: Check that the cursor was properly opened using an
OPEN CURSOR statement.

30

Error Messages

-402

Description of Error: Address of a host variable is NULL. Corrective Action: Check the addresses of each program variable (one or more have a NULL value).

-403

Description of Error: The size of a received row disagrees with the expected size. Corrective Action: Check that you are using the proper library in the program.

-404

Description of Error: A NULL control block has been passed as an argument. Corrective Action: Check that you are using the proper library in the program.

-405

Description of Error: The address of a host variable is not properly aligned. Corrective Action: Check that each program variable is aligned with the proper address boundary for variables of that type.

-406

Description of Error: Memory allocation failed. Corrective Action: Exit to the operating system command line, re-enter the program you were using, and resubmit your program.

-407

Description of Error: Error number zero received from the sqlexec process. Corrective Action: Exit to the operating system command line, re-enter the program you were using, and resubmit your program.

-408

Description of Error: Invalid message type received from the sqlexec process. Corrective Action: Exit to the operating system command line, re-enter the program you were using, and resubmit your program.

-409

Description of Error: sqlexec was not found or was not executable by the current user. Corrective Action: Check that your INFORMIXDIR environment variable is properly set. Contact your System Administrator if you need help with this action.

-410

Description of Error: PREPARE statement failed or was not executed. Corrective Action: Check that your PREPARE statement was successfully executed (a failure is often due to a syntax error).

Error Messages

31

-412

Description of Error: Command pointer is NULL. Corrective Action: The statement executed prior to the current statement returned an error that was not trapped. Re-execute the prior statement(s) and include a response to the error code returned.

-413

Description of Error: Insert attempted on unopened cursor. Corrective Action: You must rst open the cursor before executing a PUT statement.

-414

Description of Error: Insert attempted on NULL cursor. Corrective Action: Make sure you have correctly declared the cursor for insert. Check the error code returned from the DECLARE statement.

-415

Description of Error: Data conversion error discovered during PUT operation. Corrective Action: The program variable is incompatible with the data type of a column in the database. Choose an appropriate program variable or restrict the size of the data in the program variable.

-416

Description of Error: USING option with open statement is invalid for insert cursor. Corrective Action: You should use the FROM option with the PUT statement or the USING option with the EXECUTE statement.

-417

Description of Error: FLUSH can only be used on an insert cursor. Corrective Action: Make sure that you are using the correct cursor.

-420

Description of Error: Cannot execute remote sqlexec. Corrective Action: Check the setting of the SQLHOST environment variable, that the sqlexec le exists on the specied node, or that the specied node is accessible to you.

-421

Description of Error: Unknown service for execution of remote sqlexec. Corrective Action: The /etc/services le does not contain an sql entry. Check with your System Administrator about adding the required entry.

-422

Description of Error: FLUSH attempted on unopened cursor. Corrective Action: You must rst open an insert cursor before executing the FLUSH statement.

32

Error Messages

-425

Description of Error: Database is currently opened by another user. Corrective Action: Another user has an exclusive lock on the database. Wait for the lock to be released, and then retry the operation.

-426

Description of Error: Unknown values have already been supplied. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-427

Description of Error: Bind count routine called with a different count. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-428

Description of Error: Bind routine called too many times. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-430

Description of Error: Type integer does not match size. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-431

Description of Error: Type oat does not match size. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-432

Description of Error: Type date does not match size. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-433

Description of Error: Type money does not match size. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-434

Description of Error: Type decimal does not match size. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-450

Description of Error: Illegal ESQL locator, or uninitialized blob variable in 4GL. Corrective Action: An uninitialized BYTE or TEXT variable has been used in a context where an initialized variable is expected. Use the LOCATE statement to initialize the variable (INFORMIX-OnLine).
Error Messages 33

-451

Description of Error: Locator buffer too small Corrective Action: Increase the size of the locator buffer or select only part of the BLOB using subscripts.

-452

Description of Error: loc_open() failed Corrective Action: The "loc_open" routine that you supplied returned an error status. Verify that the function is correct or examine status information that it returns.

-453

Description of Error: loc_close() failed Corrective Action: The "loc_close" routine that you supplied returned an error status. Verify that the function is correct or examine status information that it returns.

-454

Description of Error: loc_read() failed Corrective Action: The "loc_read" routine that you supplied returned an error status. Verify that the function is correct or examine status information that it returns.

-455

Description of Error: loc_write() failed Corrective Action: The "loc_write" routine that you supplied returned an error status. Verify that the function is correct or examine status information that it returns.

-456

Description of Error: Indicator value cannot t in host variable. Corrective Action: This is an internal error. Please notify the Informix Technical Support Department.

-461

Description of Error: File open error. Corrective Action: Verify that the le exists and that it has the correct permissions.

-462

Description of Error: File close error. Corrective Action: Verify that the le exists and that it has the correct permissions.

-463

Description of Error: File read error. Corrective Action: Verify that the le exists and that it has the correct permissions.

34

Error Messages

-464

Description of Error: File write error. Corrective Action: Verify that the le exists and that it has the correct permissions.

-465

Description of Error: No more memory for locator buffer. Corrective Action: Exit to the operating system command line and resubmit your program.

-500

Description of Error: Clustered index index-name already exists in the table. Corrective Action: A table can have only one clustered index. You must rst alter the existing cluster index to NOT CLUSTER before creating a new clustered index.

-501

Description of Error: Index index-name is already not clustered. Corrective Action: You do not need to alter the index to NOT CLUSTER.

-502

Description of Error: Cannot cluster index. Corrective Action: Check the ISAM error code for more information about the source of the problem.

-503

Description of Error: Too many tables locked. Corrective Action: Either unlock one or more tables, or open the database in exclusive mode.

-504

Description of Error: Cannot lock a view. Corrective Action: You cannot execute the LOCK TABLE command on a view.

-505

Description of Error: Number of columns in UPDATE does not match number of VALUES. Corrective Action: The number of columns in the UPDATE statement must equal the number of values. Rewrite your SQL statement.

-506

Description of Error: Do not have permission to update all columns. Corrective Action: Obtain permission from the owner of the table. You can query the systables system catalog for this information.

-507

Description of Error: Cursor not found. Corrective Action: This cursor has not been dened. Check the spelling of cursor-name.

Error Messages

35

-508

Description of Error: Cannot rename a temporary table. Corrective Action: Remove the RENAME TABLE statement from your program.

-509

Description of Error: Cannot rename a column in a temporary table. Corrective Action: Remove the RENAME COLUMN statement from your program.

-510

Description of Error: Cannot create synonym for temporary table table-name. Corrective Action: Remove the CREATE SYNONYM statement from your program.

-511

Description of Error: Cannot modify system catalog catalog-name. Corrective Action: You do not have alter permission on any of the system catalogs. Do not attempt to modify these les.

-512

Description of Error: Cannot open database database-name in exclusive mode. Corrective Action: Another user is currently using the database. Wait until the database is no longer in use.

-513

Description of Error: Statement not available with this database engine. Corrective Action: The statement that you used is not available with the INFORMIX-OnLine database engine.

-514

Description of Error: Only DBA can create, drop, or grant for another user. Corrective Action: Ask the DBA to perform the operation for you, or to grant you DBA permission.

-515

Description of Error: Statement not available using non-INFORMIX-OnLine database server. Corrective Action: Make sure that you are using the appropriate database server (sqlexec for INFORMIX-SE or sqlturbo for INFORMIX-OnLine).

-516

Description of Error: System error-temporary output le not yet created. Corrective Action: Check the ISAM error for the source of the problem.

36

Error Messages

-517

Description of Error: The size of the index elds is too large or there are too many parts in the index. Corrective Action: Reduce the number of elds or the size of the elds in your index.

-518

Description of Error: Cannot have extent size equal to zero. Corrective Action: The extent size must be at least four pages.

-519

Description of Error: Cannot update column to illegal value. Corrective Action: Check the values in your UPDATE or INSERT statement.

-520

Description of Error: Cannot open database tblspace. Corrective Action: Check that the chunk that contains the tblspace is on-line.

-521

Description of Error: Cannot lock system catalog catalog-name. Corrective Action: You are not allowed to lock system catalogs. Check the spelling of the table to be locked.

-522

Description of Error: Table table-name not selected in query. Corrective Action: Check the spelling of the table in the query.

-523

Description of Error: You can only recover, repair, or drop a table. Corrective Action: Check to make sure that the table in the query is not a view.

-524

Description of Error: Lock table can only be used within a transaction. Corrective Action: You must start logging for the database before executing the statement.

-525

Description of Error: Cannot create databaseno system permission. Corrective Action: Make sure you have write and execute permission on the current directory.

-526

Description of Error: Updates are not allowed on a scroll cursor. Corrective Action: Do not use a scroll cursor with a statement that is declared SELECT FOR UPDATE.

-527

Description of Error: Lock mode is not available on this system. Corrective Action: Modify your program to not WAIT FOR LOCK.

Error Messages

37

-528

Description of Error: Maximum output rowsize (32767) exceeded. Corrective Action: The total number of bytes for the selected columns is greater than the maximum permitted. You should reduce the number of items in the select list. (INFORMIX-OnLine)

-529

Description of Error: Cannot attach to shared memory. Corrective Action: The shared memory might not be up. Check the ISAM error message for the specic reason.

-531

Description of Error: Duplicate column column-name exists in view. Corrective Action: Two view columns have the same name; change one of them.

-532

Description of Error: Cannot alter temporary table table-name. Corrective Action: A temporary table cannot be altered.

-533

Description of Error: Extent size too small, minimum size is size. Corrective Action: You must enter a size that is at least four pages. Reenter the statement specifying at least size kilobytes.

-534

Description of Error: Could not insert new row into table, table is locked. Corrective Action: Wait until table is unlocked, and retry the statement.

-535

Description of Error: Already in transaction. Corrective Action: You must issue a COMMIT WORK or ROLLBACK WORK statement at this point.

-536

Description of Error: Cannot have more than one cursor on the same statement. Corrective Action: Prepare another identier on the statement, and declare a cursor on that identier.

-538

Description of Error: Cursor cursor-name has already been declared. Corrective Action: Check to see where you have declared a cursor with the same name elsewhere, and change one of the cursor names.

-539

Description of Error: DBTEMP too long. Corrective Action: Shorten the pathname which you have assigned to DBTEMP, or use the default value.

38

Error Messages

-540

Description of Error: Write failed on constraints. Corrective Action: Verify that you are not trying to give a UNIQUE CONSTRAINT a name that has already been used in the database. You can check the sysconstraints table for existing UNIQUE CONSTRAINT names.

-541

Description of Error: User does not have ALTER privilege. Corrective Action: To modify the name or schema of a table, you must have ALTER privilege on the table, or be the DBA, or be the owner of the table.

-542

Description of Error: Cannot specify the same column more than once in a UNIQUE constraint. Corrective Action: Check your UNIQUE list denition to be sure that no column is specied more than once in a composite UNIQUE CONSTRAINT.

-543

Description of Error: ESCAPE character must be only one character. Corrective Action: Check your ESCAPE denition to verify that you have only specied one character as the ESCAPE character.

-544

Description of Error: Cannot have aggregates within aggregates. Corrective Action: Do not nest aggregate statements.

-545

Description of Error: No write permission for table table-name. Corrective Action: Use the UNIX chmod utility to add write permission on the appropriate .dat le.

-546

Description of Error: Cannot have host variables when creating a view. Corrective Action: Do not use host variables in a CREATE VIEW statement.

-549

Description of Error: Column column-name in UNIQUE constraint is not a column in the table. Corrective Action: Verify that the column you are specifying exists in the table. Check the spelling of the column name(s) specied in your UNIQUE list.

-550

Description of Error: Total length of columns in UNIQUE constraint is too long. Corrective Action: The maximum length for columns in a UNIQUE CONSTRAINT is 120 bytes.

Error Messages

39

-551

Description of Error: UNIQUE constraint contains too many columns. Corrective Action: The maximum number of columns in a UNIQUE CONSTRAINT is 8.

-554

Description of Error: Syntax disallowed in this database engine. Corrective Action: Check the syntax of your statement; you have used INFORMIX-OnLine syntax on INFORMIX-SE.

-555

Description of Error: Cannot use a select or any of the database statements in a multi-query prepare. Corrective Action: You cannot specify the following statements in a multi-statement prepare:
CLOSE DATABASE CREATE DATABASE DATABASE DROP DATABASE SELECT

-556

Description of Error: Cannot create, drop, or modify a remote object. Corrective Action: You can only read the contents of external tables. If you make the database your current database, you can modify the contents.

-557

Description of Error: Cannot locate remote table after count levels of synonym mapping. Corrective Action: You have used a synonym that points to a chain of synonyms, and the number of synonyms in the chain exceeds 16.

-559

Description of Error: Cannot create a synonym on top of another synonym. Corrective Action: You can only create a synonym for a table or view. Check that the synonym name that you are trying to use is not the name of an existing synonym. You can look at the systables table to nd the names of existing synonyms (where tabtype = S).

-560

Description of Error: Synonym with tabid name not found in systables. Corrective Action: Your systables system catalog might be corrupted. You may need to rebuild the catalog.

-561

Description of Error: Sums and averages cannot be computed on datetime values. Corrective Action: Do not attempt to use the SUM or AVG aggregate functions on a column of type DATETIME.

40

Error Messages

-562

Description of Error: Database conversion failed. Corrective Action: When you opened your database for the rst time with this release, the creation of the new sytem tables failed for some reason other than locking. This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-563

Description of Error: Cannot acquire exclusive lock for database conversion. Corrective Action: Someone else might have an exclusive lock on the database, or someone else might be accessing the database. Wait to run the database conversion until no one else is accessing the database.

-564

Description of Error: Cannot sort rows. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-565

Description of Error: Cannot read sorted rows. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-566

Description of Error: Cannot initiate sort. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-567

Description of Error: Cannot write sorted rows. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

Error Messages

41

-568

Description of Error: Cannot reference an external database without logging. Corrective Action: Because you are using a database with logging as your current database, you can only access remote databases that have logging. You have to turn logging on in the remote database in order to access it.

-569

Description of Error: Cannot reference an external database with logging. Corrective Action: Because you are using a database without logging as your current database, you can only access remote databases that do not have logging. You have to turn logging on in your database in order to access the remote database.

-570

Description of Error: Cannot reference an external ANSI database. Corrective Action: Because your current database is not MODE ANSI, you can only access remote databases that are also not MODE ANSI.

-571

Description of Error: Cannot reference an external non-ANSI database. Corrective Action: Because your current database is MODE ANSI, you can only access remote databases that are also MODE ANSI.

-572

Description of Error: The specied wait duration is too long. Corrective Action: The maximum wait duration for SET LOCK MODE TO WAIT is 32,767 seconds.

-573

Description of Error: Cannot set log to buffered in a mode ANSI database. Corrective Action: If you choose to make your database MODE ANSI, it will have unbuffered logging.

-574

Description of Error: A subquery has returned not exactly one column. Corrective Action: A subquery (select statement within a WHERE clause) can only have a single column or expression in its select list. Modify the subquery to contain a single column or expression.

-575

Description of Error: LENGTH( ) requires string type values. Corrective Action: You can only use the LENGTH( ) function with character columns.

42

Error Messages

-576

Description of Error: Cannot specify UNIQUE CONSTRAINT name for TEMP table. Corrective Action: You can specify a UNIQUE CONSTRAINT for a TEMP table, but you cannot specify a name for the constraint. Remove the CONSTRAINT constr-name clause from your CREATE TEMP TABLE statement.

-577

Description of Error: UNIQUE constraint already exists on the column set. Corrective Action: A UNIQUE CONSTRAINT was specied for this column set when the table was created. Check the sysconstraints table for a list of UNIQUE CONSTRAINTs for this table. (If your database is MODE ANSI, remember to prex system catalog names with informix.) Check the spelling of your UNIQUE CONSTRAINT name to verify that you are not using a name that is already assigned to a UNIQUE CONSTRAINT on this table.

-579

Description of Error: Not owner of synonym. Corrective Action: To DROP a synonym, you must be the DBA or the owner of the synonym.

-600

Description of Error: Cannot create blob. Corrective Action: Verify that you are referring to a valid blobspace.

-601

Description of Error: Cannot delete blob. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-602

Description of Error: Cannot open blob. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-603

Description of Error: Cannot close blob. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

Error Messages

43

-604

Description of Error: Cannot read blob. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-605

Description of Error: Cannot write blob. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-606

Description of Error: Invalid blob space name. Corrective Action: Check the name of the blobspace in which you are storing the BLOB data to make certain that the blobspace exists.

-607

Description of Error: Text/Byte subscript error. Corrective Action: Examine the subscripts used in the query to be certain they are positive, less than or equal to the size of the BLOB, and that the rst is smaller than the second.

-608

Description of Error: Illegal attempt to convert Text/Byte blob type. Corrective Action: BLOB types can only be selected into or created from BLOB host variables.

-609

Description of Error: Illegal attempt to use Text/Byte host variable. Corrective Action: BLOB host variables can only be used to select or create BLOB columns.

-610

Description of Error: Index not allowed on blob columns. Corrective Action: You cannot place indexes on BLOB columns.

-611

Description of Error: Scroll cursor cant select blob columns Corrective Action: You cannot select BLOB columns with a scroll cursor.

-612

Description of Error: Blobs are not allowed in the "group by" clause. Corrective Action: You cannot include a BLOB column in a GROUP BY clause; rewrite your select statement.

44

Error Messages

-613

Description of Error: Blobs are not allowed in the "distinct" clause. Corrective Action: You cannot include a BLOB column in a DISTINCT clause; rewrite your SELECT statement.

-614

Description of Error: Blobs are not allowed in the "order by" clause. Corrective Action: You cannot include a BLOB column in an ORDER BY clause; rewrite your SELECT statement.

-615

Description of Error: Blobs are not allowed in this expression. Corrective Action: Verify that BLOBs are not being used in the COUNT, SUM, MIN, MAX, and AVG aggregate functions.

-616

Description of Error: A blob subscript is not allowed within this context. Corrective Action: Verify that subscripted BLOB columns are not being used as targets for the INSERT and UPDATE statements.

-617

Description of Error: A blob data type must be supplied within this context. Corrective Action: Verify that the source and target are BLOB types.

-618

Description of Error: Error on copying blob data. Corrective Action: Verify that you are using valid blobspaces.

-620

Description of Error: Unable to update next extent size. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-621

Description of Error: Unable to update new lock level. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please record the actions that preceded this error and notify the Informix Technical Support Department.

-622

Description of Error: Error on locating UNIQUE index index-name. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

Error Messages

45

-623

Description of Error: Unable to nd UNIQUE CONSTRAINT constraint-name. Corrective Action: Check that the name of CONSTRAINT you are trying to drop exists and is spelled correctly. You can obtain this information from the sysconstraints table.

-624

Description of Error: Unable to drop UNIQUE CONSTRAINT constraint-name. Corrective Action: This is an internal error. Read the ISAM error for more information. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-625

Description of Error: UNIQUE name constraint-name already exists. Corrective Action: Specify a name that has not been used for a prior UNIQUE CONSTRAINT on this table. You can check the sysconstraints table to see the names of existing UNIQUE CONSTRAINTs.

-802

Description of Error: Cannot open le for run (operating system error). Corrective Action: Check that the le exists. If it is not found in your current directory you will need to include a full pathname. Check that you have operating system read permission to access the le. Contact your System Administrator if you need help with this action.

-804

Description of Error: Comment has no end. Corrective Action: Comments can be enclosed within a pair of { and } braces. Edit your statement to include a matching right brace } to the left brace { that denotes the start of your comment. Note: Comments cannot be nested.

-809

Description of Error: SQL syntax error has occurred. Corrective Action: Check that you have not misspelled an SQL statement, placed keywords out of sequence, or included a reserved word in your query.

-816

Description of Error: Cannot read le (check le permissions). Corrective Action: Check that you have operating system read permission to access the le. Contact your System Administrator if you need help with this action.

-817

Description of Error: Cannot write le (check le permissions). Corrective Action: Check that you have operating system write permission in the designated directory. Contact your System Administrator if you need help with this action.

46

Error Messages

-824

Description of Error: Missing values clause on insert statement. Corrective Action: The INSERT INTO statement requires a VALUES clause. Check that you have included a VALUES clause (with a values list) in your statement.

-825

Description of Error: Program not found. Corrective Action: INFORMIX-4GL could not locate a necessary program. Check that your INFORMIXDIR environment variable is properly set. Contact your System Administrator if you need help with this action.

-826

Description of Error: Fork system call failed. System Action: The statement did not run (operating system error). Corrective Action: INFORMIX-4GL was unable to fork a necessary process. Pause a moment and reenter your request. If you receive this error message again, contact your System Administrator.

-827

Description of Error: Database not found. Corrective Action: Check the spelling of the database name. Check that the database name exists in your current directory or a directory specied in your DBPATH environment variable.

-829

Description of Error: Form not found. Corrective Action: Check the spelling of the form name. Make sure the the form exists in your current directory or a directory specied in your DBPATH environment variable.

-832

Description of Error: Error(s) found in form specications. Corrective Action: Edit the form specication le following the prompts provided by FORM4GL. Recompile the form specication.

-834

Description of Error: form4gl could not compile the form. Corrective Action: Attempt a second compile of the form, or run FORM4GL outside of INFORMIX-4GL.

-836

Description of Error: Insert statement has no values clause. Corrective Action: The INSERT INTO statement requires a VALUES clause. Check that you have included a VALUES clause (with a values list) in your statement.

Error Messages

47

-837

Description of Error: There is not enough memory available. Corrective Action: There is insufcient data space in memory to run your request. Save your program, exit from INFORMIX-4GL, and then reenter INFORMIX-4GL and run your program again. If this does not work, you may need to reduce the complexity of your program.

-839

Description of Error: Table not found. Corrective Action: Check the spelling of the table name. Make sure the table-name.dat, table-name.idx, and table-name.lok les are located in the database-name.dbs directory.

-840

Description of Error: Name is too long. Corrective Action: Database names must be ten characters or less. Select a new name of the appropriate length.

-841

Description of Error: Name must start with a letter and contain letters, digits, or underscores. Corrective Action: Select a name beginning with a letter and containing only letters, digits, and underscores.

-842

Description of Error: Cannot read temp le. Corrective Action: Check that you have operating system read permission to access the le. Contact your System Administrator if you need help with this action.

-843

Description of Error: Cannot write temp le. Corrective Action: Check that you have operating system write permission to create a le in the current directory, the /tmp directory, or the directory indicated in your DBTEMP environment variable. Contact your System Administrator if you need help with this action.

-844

Description of Error: Statement is too long (maximum 2,048 characters). Corrective Action: Reduce the length of the statement to less than 2,048 characters.

-846

Description of Error: Number of values in load le is not equal to the number of columns. Corrective Action: Check that the number of values in the load le equals the number of columns in the table.

48

Error Messages

-847

Description of Error: Error in load le line line-no. Corrective Action: See the accompanying error message for information about the source of the problem. Check the load le.

-851

Description of Error: Cannot drop le (check le permissions.) Corrective Action: Check the access permissions on the le that you are trying to drop.

-852

Description of Error: Write failed. integer rows unloaded (check ulimit or disk space). Corrective Action: Check with your system administrator to verify that you have not run out of disk space.

-853

Description of Error: Current transaction has been rolled back. Corrective Action: The transaction was rolled back as a result of a syntax error in your SQL statement or .sql le. Check the syntax of your SQL statements and retry the statement.

-900

Description of Error: Cannot read network user authorization le. Corrective Action: Check that the network user authorization le exists on the server, that it is accessible through the network, and that you have read permission.

-901

Description of Error: User not found in network user authorization le. Corrective Action: Add the user to the network authorization le.

-902

Description of Error: User not authorized or too many entries in authorization le. Corrective Action: Requires a version congured for more users. Contact Informix Software for assistance.

-904

Description of Error: Authorization le not on licensed INFORMIX-SQL server. Corrective Action: Reset the INFORMIXDIR variable to the directory that contains the licensed software.

-907

Description of Error: Cannot create socket on local system. Corrective Action: Check that TCP/IP is installed and functioning properly throughout the network.

Error Messages

49

-908

Description of Error: Attempt to connect to remote system failed. Corrective Action: Verify that the remote system is up and functioning properly. Check that the sqlexecd process on the remote system is running as a background process and was started by root.

-909

Description of Error: Invalid database name format. Corrective Action: Check that you have provided the remote database name in one of the forms explained in the INFORMIX-OnLine Programmers Manual.

-910

Description of Error: Cannot create an INFORMIX-OnLine database from an

INFORMIX-SE client.

Corrective Action: Use an INFORMIX-OnLine client to create the database. -911 Description of Error: System error - Cannot read from pipe. Corrective Action: Reenter your request. If the problem persists, refer to your system manual for more information about the source of the problem. -912 Description of Error: Network error - Could not write to remote system. Corrective Action: Reenter your request. If the problem persists, run your network diagnostics to determine the source of the problem. -913 Description of Error: Network error - Could not read from remote system. Corrective Action: Reenter your request. If the problem persists, run your network diagnostics to determine the source of the problem. -914 Description of Error: System error - Cannot write to pipe. Corrective Action: Reenter your request. If the problem persists, refer to your system manual for more information about the source of the problem. -915 Description of Error: Cannot create an INFORMIX-SE database from an INFORMIX-OnLine client. Corrective Action: Use an INFORMIX-SE client to create the database. -916 Description of Error: Cannot open /etc/mtab. Corrective Action: Make sure that /etc/mtab is readable by the user. -917 Description of Error: Must close current database before using a new database. Corrective Action: Close the current database and reenter your request for a new database.

50

Error Messages

-918

Description of Error: Unexpected data received from remote system. Corrective Action: Reenter your request. If the problem persists, run your network diagnostics to determine the source of the problem.

-919

Description of Error: System error. Wrong number of arguments to remote sqlexec process. Corrective Action: Reenter your request. If the problem persists, refer to your system manual for more information about the source of the problem.

-922

Description of Error: System error. Unable to fork remote sqlexec process. Corrective Action: Check operating system permissions for the directory, and make sure that you have permission to access the directory.

-925

Description of Error: The protocol type should be tcp. Corrective Action: Change the protocol type to tcp in $INFORMIXDIR/etc/sqlhosts.

-926

Description of Error: INFORMIX-OnLine is not licensed for distributed data access. Corrective Action: You cannot access tables or databases on remote systems unless you have INFORMIX-STAR.

-927

Description of Error: Exceeded limit of maximum number of sites you can reference. Corrective Action: The maximum number of sites that you can reference is 32.

-928

Description of Error: The remote server is not licensed for distributed data access. Corrective Action: You have tried to access a table on an INFORMIX-OnLine system that is not licensed for remote access. You can only access other INFORMIX-STAR systems.

-930

Description of Error: Cannot connect to remote host sitename. Corrective Action: Check that the sitename that you are using is correct. Verify that the sitename has an entry in the required networking les.

-931

Description of Error: Cannot locate service-name service/tcp service in /etc/services. Corrective Action: Check the /etc/services le on the client for the required entries.
Error Messages 51

-932

Description of Error: Error on network connection, system-call system call failed. Corrective Action: Check that your network hardware and software are installed and functioning properly throughout the network.

-933

Description of Error: Unknown network type specied in DBNETTYPE. Corrective Action: Set your environment variable DBNETTYPE to starlan, tcp/ip, or some other supported network.

-951

Description of Error: User is not known on remote host. Corrective Action: Verify that the user has a login on the host, and that the network software is congured properly to accept this user name. Consult your machine and network user manuals for assistance.

-952

Description of Error: Users password is not correct for the remote host. Corrective Action: Check your /etc/hosts.equiv le to be sure that both the host machine you are attempting to connect to and the client machine you are currently logged into have entries in the le. If not, add the missing entry and reenter your request.

-953

Description of Error: Remote host could not execute sqlexec program. Corrective Action: Verify that the INFORMIXDIR environment variable was set on the server when the sqlexecd network server process was started by root. If not, do this now and restart the sqlexecd process in the background.

-954

Description of Error: Client is not known to remote host. Corrective Action: Verify that the host is aware of the client machine on the network. If you are using TCP/IP, check your /etc/hosts le. Consult your network user manual for assistance.

-955

Description of Error: Remote host could not receive data from client. Corrective Action: Verify that both the host machine and the client machine are congured properly, and that both machines are aware of each other on the network. Consult your network user manual for assistance.

-956

Description of Error: Client is not in the le. /etc/hosts.equiv on the remote host. Corrective Action: Verify that the client machine name is in the /etc/hosts.equiv le on the remote host machine.

52

Error Messages

-999

Description of Error: Long transaction aborted. Corrective Action: Your transaction has either lled up all of the available logical log space or it was waiting for a lock held by a transaction that lled all of the log space. If your transaction is long, decrease the length of the aborted transaction and retry. You can also increase the number of logical logs on your system. If your transaction is not long, but it waits for locks, you can retry the transaction and, depending on the timing, it might not conict with the long transaction again. Increasing the number of logical log les on your system might also help, if your process is conicting with other processes that have long transactions.

-1101

Description of Error: Variable address is NULL. Corrective Action: After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-1102

Description of Error: Field name not found in form. Corrective Action: A eld name listed in an INPUT, INPUT ARRAY, DISPLAY, DISPLAY ARRAY, or CONSTRUCT statement does not appear in the form specication le of the screen form that is currently displayed. Change the eld name in the program or form specication le as appropriate and recompile.

-1107

Description of Error: Field subscript out of bounds. Corrective Action: The subscript of a screen array in an INPUT, INPUT ARRAY, DISPLAY, DISPLAY ARRAY, or CONSTRUCT statement is larger than the corresponding subscript in the SCREEN RECORD statement that denes the screen array in the form specication le. Change the subscript in your program or make the appropriate modications to your form specication le.

-1108

Description of Error: Record not in form. Corrective Action: The screen record in an INPUT, INPUT ARRAY, DISPLAY, DISPLAY ARRAY, or CONSTRUCT statement does not appear in the form specication le. Change the screen record name in your program or in your form specication le.

-1109

Description of Error: List and record eld counts differ. Corrective Action: The number of program variables or columns is not the same as the number of elds in an INPUT, INPUT ARRAY, DISPLAY, DISPLAY ARRAY, or CONSTRUCT statement. Check the variable-list or column-list and the eld-list to make sure they contain the same number of items.

Error Messages

53

-1110

Description of Error: Form le not found. Corrective Action: The form le specied in the OPEN FORM statement could not be found. Make sure that your program can access the form le specied in the OPEN FORM statement.

-1111

Description of Error: Field table offset out of bounds. Corrective Action: After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-1112

Description of Error: A form is incompatible with the current 4GL version. Rebuild your form. Corrective Action: The form le specied in an OPEN FORM statement has been corrupted, or was compiled with an older version of FORM4GL. Recompile the form specication le with the appropriate version of FORM4GL. Note: Do not specify a le extension with the form name in an OPEN FORM statement.

-1113

Description of Error: Memory allocation error. Corrective Action: Divide your program into smaller programs.

-1114

Description of Error: No form has been displayed. Corrective Action: Make sure you successfully execute an OPEN FORM statement before a DISPLAY FORM statement.

-1115

Description of Error: Numeric value too long for eld. Corrective Action: Please check the entered value and make the necessary correction.

-1116

Description of Error: Default value from form eld cannot be converted to input variable type. Corrective Action: The default value in a display eld is not compatible with the data type of the corresponding program variable in an INPUT or INPUT ARRAY statement. Change the default value for the display eld or change the data type of the corresponding variable in the INPUT or INPUT ARRAY statement.

-1117

Description of Error: Cannot convert date value to string. Corrective Action: A DATE value in the database cannot be converted to a string. If the correct date is known, update the table to substitute a valid DATE value.

54

Error Messages

-1119

Description of Error: NEXT FIELD name not found in form. Corrective Action: The eld name in the NEXT FIELD clause of an INPUT or INPUT ARRAY statement does not appear in the eld-list of the statement. Change the NEXT FIELD clause or the eld-list as appropriate.

-1120

Description of Error: Message le not found. Corrective Action: The message le specied in the HELP FILE clause of the OPTIONS statement either could not be found or could not be read. Make sure your program can access the message le specied in the OPTIONS HELP FILE statement.

-1121

Description of Error: Message number not found in message le. Corrective Action: A message number in an INPUT, PROMPT, or MENU statement does not appear in the corresponding message le. Change the message number in your program or add a new message to the le and recompile.

-1122

Description of Error: Incompatible message le. Corrective Action: The message le specied in the HELP FILE clause of the OPTIONS statement could not be read. Make sure the OPTIONS HELP FILE statement species a compiled message le that is readable.

-1129

Description of Error: Field in BEFORE/AFTER clause not found in form. Corrective Action: A eld name in the BEFORE or AFTER clause of an INPUT or INPUT ARRAY statement does not appear in the form specication le of the screen form that is currently displayed. Change the eld name in the program or form specication le as appropriate and recompile.

-1130

Description of Error: You cannot have multiple BEFORE clauses for the same eld. Corrective Action: Combine the BEFORE clauses for the same eld in INPUT or INPUT ARRAY statements.

-1131

Description of Error: You cannot have multiple AFTER clauses for the same eld. Corrective Action: Combine the AFTER clauses for the same eld in INPUT or INPUT ARRAY statements.

Error Messages

55

-1132

Description of Error: The destination string of the CONSTRUCT statement is not large enough. Corrective Action: The character variable for storing the users search criteria in a CONSTRUCT statement is not large enough to contain the constructed string. Increase the size of the character variable in the appropriate DEFINE statement and recompile your program.

-1133

Description of Error: The NEXT OPTION name is not in the menu. Corrective Action: The NEXT OPTION name is not a menu option. Change the menu option in the NEXT OPTION statement or the menu as appropriate and recompile your program.

-1134

Description of Error: There is no termcap entry for this function key. Corrective Action: The specied key in the HELP KEY, INSERT KEY, DELETE KEY, NEXT KEY, or PREVIOUS KEY clause of an OPTIONS statement does not appear in the termcap or terminfo les. Add the code for the specied function key to the termcap le, or add the code to your terminal le in the terminfo directory. See Appendix I of the INFORMIX-4GL Reference Manual for details.

-1135

Description of Error: The row or column number in DISPLAY AT exceeds the limits of your terminal. Corrective Action: Change the row or column number in the DISPLAY AT statement so that it is within the limits of your screen or window.

-1136

Description of Error: Window is too large to t on the screen. Corrective Action: The window dimensions specied in the WITH clause of the OPEN WINDOW statement exceed the limits of your screen. Reduce the size of the window dimensions, or change the originating location of the window. If you are attempting to open the window WITH FORM, you must reduce the size of the form. (When sizing a window to t a form, INFORMIX-4GL truncates trailing blank spaces but prints leading blank spaces. You might remove any leading blank spaces.)

-1137

Description of Error: Cannot open window. Corrective Action: Your INFORMIX-4GL program exceeds the data space limit of your system. Reduce the complexity of the program by closing one or more windows or forms, or reducing the number of global variables.

56

Error Messages

-1138

Description of Error: Border does not t on screen. Window is too large. Corrective Action: The dimensions of the bordered window exceed the limits of your screen. Note that the border appears outside the dimensions of the window. Reduce the size of the window dimensions. If the termcap entry for your terminal includes an sg#1 setting, or the terminfo entry includes an xmc#1 setting, INFORMIX-4GL reserves an additional column to the left and to the right of the window when computing the required window size.

-1139

Description of Error: Form line cannot be set using LAST keyword. Corrective Action: You cannot use LAST or LAST-integer to set the Form line. You must indicate the Form line relative to FIRST or a literal value.

-1141

Description of Error: Cannot close window with active INPUT, DISPLAY

ARRAY, or MENU statement.

Corrective Action: You must complete the INPUT, DISPLAY ARRAY, or MENU statement before closing the current window. -1142 Description of Error: Window is too small to display this form. Corrective Action: The window dimensions specied in the WITH clause of the OPEN WINDOW statement are too small for the form. Either open the window WITH FORM, or increase the dimensions in the WITH clause. -1143 Description of Error: Window is already open. Corrective Action: You cannot issue an OPEN WINDOW statement for a window that is already open. Check your program logic to see whether you should add a CLOSE WINDOW statement or delete an OPEN WINDOW statement. -1144 Description of Error: Cannot open window. Window origin is not on the screen. Corrective Action: The originating location specied in the AT clause of the OPEN WINDOW statement exceeds the limits of the screen. Specify a new location. -1145 Description of Error: Cannot open ERROR window. Corrective Action: Your INFORMIX-4GL program exceeds the data space limits of your system. Reduce the complexity of the program by closing one or more windows or forms, or reducing the number of global variables.

Error Messages

57

-1146

Description of Error: PROMPT message is too long to t in the window. Corrective Action: Reduce the length of the PROMPT statement or enlarge the window. You will receive a run-time error if the window does not accommodate the text of the PROMPT message along with the characters entered by the user in response to the prompt. Note: if necessary, INFORMIX-4GL truncates MESSAGE and COMMENT text. INFORMIX-4GL does not truncate the text of a PROMPT statement.)

-1147

Description of Error: You cannot CLOSE, CLEAR, or make CURRENT an unopened window. Corrective Action: Check that you specied the correct window. You must rst execute an OPEN WINDOW statement before executing a CLOSE WINDOW, CLEAR WINDOW, or CURRENT WINDOW statement. In addition, you cannot execute these statements once the window is CLOSEd.

-1148

Description of Error: Size of a window may not be negative. Corrective Action: Only positive integers or variables that evaluate to positive integers can be used in the WITH clause of the OPEN WINDOW statement.

-1149

Description of Error: An unknown code has been detected in the form. Corrective Action: Be sure that you have linked your 4GL program with the correct 4GL libraries. Relink your INFORMIX-4GL program with the most recent version of the INFORMIX-4GL libraries. Rebuild your form with FORM4GL.

-1150

Description of Error: Window is too small to display this menu. Corrective Action: Increase the dimensions of the window to accommodate the menu. At a minimum, the window must be two rows long and large enough to display the menu title and a colon, the longest option, two sets of ellipses, and 6 spaces.

-1200

Description of Error: Number is too large for a DECIMAL data type. Corrective Action: The range of numbers allowed as DECIMAL values has been exceeded. Allowable decimal numbers range from 10-128 to 10126 in absolute value (with 32 signicant digits). Check the size of the number.

-1201

Description of Error: Number is too small for a DECIMAL data type. Corrective Action: A number is outside the range of DECIMAL type values. Allowable decimal numbers range from 10-128 to 10126 in absolute value (with 32 signicant digits). Check the size of the number.

58

Error Messages

-1202

Description of Error: An attempt was made to divide by zero. Corrective Action: Check that you are not attempting to divide a number data type by a character data type (for example, 16/Jones) or that the value of the divisor does not equal zero.

-1203

Description of Error: Values used in a MATCH must both be type CHARACTER. Corrective Action: Check that the values included in your MATCH condition are CHAR or VARCHAR types. Use an alternate comparison condition for non-character data types.

-1204

Description of Error: Invalid year in date. Corrective Action: Acceptable years are 0001 to 9999. If two digits are used, INFORMIX-4GL assumes the year is 19xx. Check the value entered in the DATE eld.

-1205

Description of Error: Invalid month in date. Corrective Action: In SQL statements such as INSERT, a month can be represented as the number of the month (1 through 12). In display elds, a month can be represented either as the number of the month (1 through 12) or as the rst three letters of the name of the month. Check the value entered in the DATE column or eld.

-1206

Description of Error: Invalid day in date. Corrective Action: Acceptable days are 01 through 31, unless the month has fewer days. Check the value entered in the DATE column or eld.

-1208

Description of Error: There is no conversion from non-character values to character values. Corrective Action: Number values cannot be converted to character values in SQL statements such as INSERT and UPDATE. Make sure that your SQL statements do not attempt this kind of conversion.

-1209

Description of Error: Without any delimiters, this date must contain exactly 6 or 8 digits. Corrective Action: You must enter either 6 or 8 digits when specifying a data value to represent a DATE.

Error Messages

59

-1210

Description of Error: Date could not be converted to month/day/year format. Corrective Action: Dates must be presented as month, day, and year (so August 4, 1989 is allowed, but 4 August, 1989 is not). Check the sequence of characters entered in the DATE eld.

-1211

Description of Error: Out of memory. Corrective Action: You have exceeded the data space capacity on your machine. Reduce the complexity of your form.

-1212

Description of Error: Date conversion format string must contain a month, day, and year component. Corrective Action: The FORMAT string used to format a DATE eld must contain month, day, and year components. One of these is missing.

-1213

Description of Error: Character to numeric conversion error. Corrective Action: Check that the values in the character string contain only ASCII characters representing number data types. (A table of ASCII codes is included as Appendix H to this manual.)

-1214

Description of Error: Value too large to t in a SMALLINT. Corrective Action: Acceptable SMALLINT values are whole numbers between -32,767 and 32,767. If a larger number is required, use the ALTER TABLE statement to modify the column to INTEGER type.

-1215

Description of Error: Value too large to t in an INTEGER. Corrective Action: Acceptable INTEGER values are whole numbers between -2,147,483,647 and 2,147,483,647. If a larger number is required, use the ALTER TABLE statement to modify the column to DECIMAL type.

-1216

Description of Error: Illegal exponent. Corrective Action: Check that the exponent is an integer with a value not exceeding 32,767.

-1217

Description of Error: The format string is too large. Corrective Action: Reduce the size of the FORMAT string (used to format a DATE eld) in the form specication.

-1218

Description of Error: String to date conversion error. Corrective Action: Check the format for the DATE data type in the DBDATE environment variable. The format is illegal.

60

Error Messages

-1222

Description of Error: Value will not t in a SMALLFLOAT. Corrective Action: Enter the appropriate value, depending on the machine that you use.

-1223

Description of Error: Value will not t in a FLOAT. Corrective Action: Enter the appropriate value depending on the machine you use.

-1224

Description of Error: Invalid decimal number. Corrective Action: The value that you entered might be out of range. Refer to the decimal value created at the time when you created the column.

-1225

Description of Error: Column does not admit a NULL value. Corrective Action: This column does not accept NULL values. Make sure that the data value that you are attempting to insert is not NULL.

-1226

Description of Error: Decimal or money value exceeds maximum precision. Corrective Action: Increase the precision of the DECIMAL or MONEY eld.

-1227

Description of Error: Message le not found. Corrective Action: Check to see if you have installed the product correctly. Alternately, you might be missing a message le. Search for the required message le.

-1228

Description of Error: Message number not found in message le. Corrective Action: You might have a corrupted message le. Retrieve an uncorrupted message le by re-installing the product (or by re-editing and recompiling 4glusr.msg, if you changed a message number in that le).

-1229

Description of Error: Incompatible message le. Corrective Action: Retrieve uncorrupted version of message le by reinstalling the product.

-1230

Description of Error: Bad message le name formulation. Corrective Action: Check to see if you have entered the correct message le names.

-1231

Description of Error: Cannot seek within message le. Corrective Action: Re-install or rebuild your message les.

Error Messages

61

-1232

Description of Error: Message buffer too small. Corrective Action: You may be out of memory. The internal buffer for Help and other messages defaults to 128 bytes, but automatically resizes itself to accommodate longer messages. This error usually means that your program is reading a very large le as a single message, or else that it is mistakenly reading memory instead of a message le. Make sure that your message le format is correct, and then recompile it.

-1250

Description of Error: Unable to create pipes. Corrective Action: Check the spelling of the name of the program receiving the output. Check that the program is available on your system. Check that the program exists in a directory accessed in your PATH environment variable. Contact your System Administrator if you need help with these actions.

-1251

Description of Error: Unable to create shared memory. semget failed. Corrective Action: This is an internal error. Follow the suggested actions for error -1250. You may also be out of memory. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.

-1252

Description of Error: Unable to create shared memory. shmget failed. Corrective Action: This is an internal error. Follow the suggested actions for error -1250. You may also be out of memory. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.

-1254

Description of Error: Unable to connect to remote host. Corrective Action: Follow the suggested actions for error -1250. Make sure that the network is operating properly, and check your spelling of the identier of the remote system.

-1257

Description of Error: Operating system cannot fork process for back end. Corrective Action: This is an internal error. Follow the suggested actions for error -1250. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.

-1258

Description of Error: Cannot attach to shared memory used to communicate with back end. Corrective Action: This is an internal error. Follow the suggested actions for error -1250. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.

62

Error Messages

-1260

Description of Error: It is not possible to convert between the specied types. Corrective Action: A data type conversion must make sense; some, such as INTERVAL to DATE, or DATETIME to MONEY, are not supported. You may have referenced the wrong variable or column. Make sure that you have specied the data types that you intended, and that any strings representing data values are correctly formatted.

-1261

Description of Error: Too many digits in the rst eld of datetime or interval. Corrective Action: Specify fewer digits. The default precision is two (2) digits for every eld, except year (4) and fraction (3). You can specify a nondefault precision for fraction in the range 1 to 5. For the INTERVAL (but not DATETIME) data type, you can specify a non-default precision of up to 9 digits for any eld except fraction.

-1262

Description of Error: Non-numeric character in datetime or interval. Corrective Action: You can only use digits and the required hyphen ( - ), blank ( ), colon ( : ), and period ( . ) separators in DATETIME and INTERVAL constants, or as the values within literals. See if you used the wrong separator, included an extraneous blank, omitted a digit, omitted a separator, or entered the name of a month or day in place of digits.

-1263

Description of Error: A eld in a datetime or interval is out of range. Corrective Action: In an INTERVAL eld, the absolute value of any eld can range from 0 to 10n -1, for n the declared precision. In a DATETIME value, the year can range from 1 to 9999, the month from 1 to 12, and the day from 1 to a maximum from 28 to 31, depending on the specic month and year. The hour must be a positive integer in the range 0 to 23. The minute and second must be positive integers in the range 0 to 59. The fraction can range from 0 to 10n -1, for n the declared precision for the fraction eld.

-1264

Description of Error: Extra characters at the end of a datetime or interval. Corrective Action: See if you have included a blank within a eld, entered too many digits or too many elds, neglected the effect of an EXTEND function, or made a typing mistake.

Error Messages

63

-1265

Description of Error: Overow occurred on a datetime or interval operation. Corrective Action: Both DATETIME and INTERVAL values are stored internally as decimals. Your arithmetic operation produced a decimal overow. Examine your program logic to see if you can change the sequence or precision of your operations to avoid the overow.

-1266

Description of Error: Intervals or Datetimes are incompatible for the operation. Corrective Action: The arithmetic operations permitted on INTERVAL and DATETIME (and DATE) values are listed in Appendix J. You may have reversed the order of operands, or attempted a meaningless operation, such as adding two DATETIME values. Correct the logic of your program.

-1267

Description of Error: The result of a datetime computation is out of range. Corrective Action: The range of allowed values for DATETIME and INTERVAL elds is described in the suggested actions for error -1263. Some eld in your result (probably the rst) is too large, or is negative, or has an invalid zero value. Check the terms in your calculation and your program logic to see if you can change the sequence, scale, or precision of your operation to avoid the out-of-range results.

-1268

Description of Error: Invalid datetime qualier. Corrective Action: Check spelling. You are restricted to the keywords YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and FRACTION. Do not append S to a keyword.

-1269

Description of Error: Locator conversion error. Corrective Action: This is an internal error. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.

-1270

Description of Error: Interval literal may not have embedded minus sign. Corrective Action: You can use a minus sign as an arithmetic or unary operator with INTERVAL literals, but not within any of its elds.

-1271

Description of Error: Missing decimal point datetime or interval. Corrective Action: Use the decimal point ( . ) to separate the second and fraction elds, if both are present.

64

Error Messages

-1301

Description of Error: This value is not among the valid possibilities Corrective Action: The system issues this warning during an INPUT or INPUT ARRAY statement when the user tries to enter data outside the range(s) specied for the eld via the INCLUDE attribute in the form specication. Be sure to enter a value that appears in the INCLUDE list in the form specication le.

-1302

Description of Error: The two entries were not the sameplease try again. Corrective Action: The system issues this warning during an INPUT or INPUT ARRAY statement when the user does not enter the same value twice in a display eld that has been assigned the VERIFY attribute. The user must enter the same value twice before the value will be accepted.

-1303

Description of Error: You cannot use this editing feature because a picture exists. Corrective Action: The system issues this warning during an INPUT or INPUT ARRAY statement when the user tries to use CTRL-A, CTRL-D, or CTRL-X in a display eld that has been assigned the PICTURE attribute. The user should not use the CTRL-A, CTRL-D, or CTRL-X keys when entering data in a eld that has been assigned the PICTURE attribute.

-1304

Description of Error: Error in eld. Corrective Action: The system issues this warning when the user tries to enter a value in a display eld that cannot be converted to the data type of the corresponding program variable in the INPUT or INPUT ARRAY statement. The user must enter a value in a display eld that is compatible with the data type of the corresponding program variable in the INPUT or INPUT ARRAY statement.

-1305

Description of Error: This eld requires an entered value. Corrective Action: The system issues this warning during an INPUT or INPUT ARRAY statement when the user tries to end input without entering a value in a display eld that has been assigned the REQUIRED attribute. The user must enter a value in the required eld.

-1306

Description of Error: Please type again for verication. Corrective Action: The system issues this message during an INPUT or INPUT ARRAY statement after the user enters a value once in a display eld that has been assigned the VERIFY attribute. The user should enter the same value again.

Error Messages

65

-1307

Description of Error: Cannot insert another rowthe input array is full. Corrective Action: The system issues this warning during an INPUT ARRAY statement when the user tries to insert a row after the program array is full. The user should select another editing function or end input. If the user receives this warning frequently, the user should have the applications designer increase the size of the program array.

-1308

Description of Error: Cannot delete rowit has no data. Corrective Action: The system issues this warning during an INPUT ARRAY statement when the user selects the delete function while the cursor is on the blank row below the last row of the program array. The user should select another editing function or end input.

-1309

Description of Error: There are no more rows in the direction you are going. Corrective Action: The system issues this warning during an INPUT ARRAY or DISPLAY ARRAY statement when the user presses the [ ] or Previous Page key while the cursor is at the beginning of the program array or when the user presses the [ ] or Next Page key while the cursor is at the end of the program array. The user should select another scrolling or editing function.

-1312

Description of Error: FORMS statement error number integer. Corrective Action: Something is wrong with the input, display, or data type conversion that your program species. Refer to the corresponding error number in this manual. (This error can occur with statements that do not use screen forms.)

-1313

Description of Error: SQL statement error number integer. Corrective Action: Refer to the corresponding error number in this manual.

-1314

Description of Error: Program stopped at module, line number integer. Corrective Action: Look for additional messages to see why execution stopped.

-1315

Description of Error: 4GL run-time error number integer. Corrective Action: Refer to the corresponding error number in this manual.

-1316

Description of Error: ISAM error number integer. Corrective Action: Refer to the corresponding error number in this manual.

66

Error Messages

-1317

Description of Error: A numeric conversion error has occurred due to incompatibility between a calling program and its function parameters or between a variable and its assigned expression. Corrective Action: Make sure that the data types of variables or function parameters are compatible with the types of values assigned to them.

-1318

Description of Error: A parameter count mismatch has occurred between the calling function and the called function. Corrective Action: Make sure that the number of parameters in the calling statement is the same as the number of parameters in the called function.

-1319

Description of Error: The 4GL program has run out of runtime data space memory. System Action: The program stops and running transactions are rolled back. Corrective Action: Divide your program into smaller modules. Reduce the size of arrays and character variables. Make sure that no function returns a character string longer than 512 characters.

-1320

Description of Error: A function has not returned the correct number of values expected by the calling function. Corrective Action: Make sure that the number of parameters after the RETURN keyword in the called function is the same as the number of parameters after the RETURNING keyword in the calling statement.

-1321

Description of Error: A validation error has occurred as a result of the VALIDATE command. Corrective Action: Make sure that the values of the variables in a VALIDATE statement conform to the values allowed for the corresponding columns in the syscolval table.

-1322

Description of Error: A report output le cannot be opened. Corrective Action: Check that you have operating system write permission in the designated directory. Contact your System Administrator if you need help with this action.

-1323

Description of Error: A report output pipe cannot be opened. Corrective Action: Check the spelling of the name of the program receiving the output. Check that the program is available on your system. Check that the program exists in a directory accessed in your PATH environment variable. Contact your System Administrator if you need help with these actions.

Error Messages

67

-1324

Description of Error: A report output le cannot be written to. Corrective Action: Check that you have WRITE access to the le in the designated directory. Contact your System Administrator if you need help with this action.

-1325

Description of Error: PRINT FILE errorcannot open le lename for reading. Corrective Action: Check that the specied le exists, and that you have READ access to it. Contact your System Administrator if you need help with this action.

-1326

Description of Error: An array variable has been referenced outside of its specied dimensions. Corrective Action: Check that the number of subscripts for the array corresponds to the number of dimensions specied in the array denition. Check that the subscript(s) do not exceed the value(s) specied in the array denition. Compile with the -a option to check array dimensions.

-1327

Description of Error: An insert statement could not be prepared for inserting rows into a temporary table used for a report. Corrective Action: Check to see that you have CONNECT permission to the database used by the program. Set all system access permissions to allow you to write into the database directory.

-1328

Description of Error: A temporary table needed for a report could not be created in the selected database. The user must have permission to create tables in the selected database. Corrective Action: Check that the user has CONNECT privilege for the selected database. Check the error number that appears with this error for more information about the source of the problem.

-1329

Description of Error: A database index could not be created for a temporary database table needed for a report. Corrective Action: Check the error number that appears with this error for more information about the source of the problem.

-1330

Description of Error: A row could not be inserted into a temporary report table. Corrective Action: Check the error number that appears with this error for more information about the source of the problem.

68

Error Messages

-1331

Description of Error: A row could not be fetched from a temporary report table. Corrective Action: Check the error number that appears with this error for more information about the source of the problem.

-1332

Description of Error: A character variable has referenced subscripts that are out of range. Corrective Action: Make sure that a subscript for a character variable does not exceed the number of characters specied in the variable denition.

-1333

Description of Error: Strings of length > 512 cannot be returned from function calls. Corrective Action: Make sure that a character string returned by a function does not exceed 512 characters.

-1334

Description of Error: The 4GL program cannot allocate any more space for temporary string storage. Corrective Action: INFORMIX-4GL cannot allocate more than 512 characters for temporary string storage. This error can occur if the nested functions in a CALL statement return strings whose total length exceeds 512 characters.

-1335

Description of Error: A report is accepting output or being nished before it has been started. Corrective Action: Be sure that the program runs START REPORT before it attempts to run OUTPUT TO REPORT or FINISH REPORT.

-1336

Description of Error: Module module-name in the pcode le contains pcode version num1. This program can run pcode version num2. Run the pcode compiler with -V to check the pcode version that it produces, and then recompile all modules of your program and run it again. Corrective Action: Check the p-code version, recompile, and run the modules.

-1337

Description of Error: The variable variable-name has been redened with a different type or length. Corrective Action: The lengths and types of global variables in two modules must be consistent. Make the denitions consistent and recompile the program.

Error Messages

69

-1338

Description of Error: The function function-name has not been dened in any module in the program. Corrective Action: This suggests that the function function-name has been called, but is not in any module in the program. Supply the function in one of the modules and recompile.

-1339

Description of Error: Global variable variable-name cannot be found in the descriptor table. Corrective Action: Please call your Informix representative.

-1340

Description of Error: The error log has not been started. System Action: The ERRORLOG (message) library function does not append a message to the error log. Corrective Action: Be sure to include a CALL STARTLOG (full-pathname) statement if you want to maintain an error log.

-1343

Description of Error: No help le specied. Corrective Action: The user pressed the Help key before an OPTIONS HELP FILE statement was executed. Make sure to execute the appropriate OPTIONS HELP FILE statement before allowing the user to request help during an INPUT, PROMPT, or MENU statement.

-1345

Description of Error: Undened opcode. Corrective Action: A function cannot be executed because your p-code le has become corrupted. Recompile your source code.

-1346

Description of Error: Number is too large for a DECIMAL data type. Corrective Action: The range of values allowed as a DECIMAL data type has been exceeded. Allowable decimal numbers range from 10-128 to 10126 in absolute value (with 32 signicant digits). Check the size of the number.

-1347

Description of Error: Number is too small for a DECIMAL data type Corrective Action: The range of values allowed as a DECIMAL data type has been exceeded. Allowable decimal numbers range from 10-128 to 10126 in absolute value (with 32 signicant digits). Check the size of the number.

-1348

Description of Error: An attempt was made to divide by zero. Corrective Action: Check that you are not attempting to divide a number column type by a character column type (for example, 1990/Three) or that the value of the divisor does not equal zero.

70

Error Messages

-1349

Description of Error: Character to numeric conversion error. Corrective Action: Check that the values in the character string contain only ASCII characters representing number data types. (A table of ASCII codes is included as Appendix H to this manual.)

-1350

Description of Error: It is not possible to convert between the specied types. Corrective Action: Examine your code to make sure that you have specied the data types that you intended, and that any date or time expressions are correctly formatted. Some conversions (such as INTERVAL to MONEY) are not supported, because the meaning of the conversion is obscure.

-1353

Description of Error: Use ! to edit TEXT and BYTE elds. Corrective Action: The INFORMIX-4GL editors cannot modify TEXT and BYTE elds. BLOB values can be modied only by outside programs, such as spreadsheets, word-processors, and so forth. Use the PROGRAM attribute in the form specication le to specify the outside program for this eld. Press the exclamation point ( ! ) key to invoke the outside program.

-1355

Description of Error: Cannot build temporary le. Corrective Action: There is insufcient disk space to build a temporary copy of the TEXT or BYTE variable.

-1356

Description of Error: Write error on temporary le lename. Corrective Action: An I/O error occurred while trying to write the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.

-1357

Description of Error: Read error on temporary le lename. Corrective Action: An I/O error occurred while trying to read the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.

-1358

Description of Error: Write error on blob le lename. Corrective Action: An I/O error occurred while trying to write the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.

-1359

Description of Error: Read error on blob le lename Corrective Action: An I/O error occurred while trying to read the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.
Error Messages 71

-1360

Description of Error: No "PROGRAM=" clause for this eld. Corrective Action: This key ( ! ) invokes an editing program that can be specied by the PROGRAM attribute. If you want to access that editor, you must rst assign the PROGRAM attribute to this eld in the ATTRIBUTES section of the form specication le, and then use FORM4GL to recompile the screen form.

-1361

Description of Error: Illegal blob le name. Null names are not permitted. Corrective Action: You must specify a valid name for the le that contains this binary large object (BLOB) of data type TEXT or BYTE.

-2013

Description of Error: The output form le lename cannot be opened. Corrective Action: Check that you have operating system write permission in the designated directory. Contact your System Administrator if you need help with this action.

-2014

Description of Error: There was an incorrect number of arguments on the operating system command line. At least one argument is expected. Corrective Action: FORM4GL requires that you include a lename on the command line (unless you use the -d option to FORM4GL). Carefully reenter the command, including the lename as an argument, or use the -d option to FORM4GL. The correct syntax is as follows: form4gl form-name

-2015

Description of Error: An open comment symbol, {, was found inside an already open comment on line lineno, character charposition. This could be due to a failure to close the previously opened comment, which was begun on line lineno, character charposition. Corrective Action: Comments must be enclosed within a pair of braces ({ and }). Insert a close comment symbol where appropriate. (Note: comments cannot be nested.) Recompile the form specication.

-2016

Description of Error: A comment has been opened, but not closed. The last comment begun was opened on line lineno, character charposition. Corrective Action: Comments must be enclosed within a pair of braces ({ and }). Insert a close comment symbol where appropriate. Recompile the form specication.

-2017

Description of Error: The character data value does not convert correctly to the eld type. Corrective Action: Check that the values in the character string contain only ASCII characters, and represent a value of the appropriate data type. See if a date or time separator is incorrect.

72

Error Messages

-2018

Description of Error: A grammatical error has been found on line lineno, character charposition. The construct is not understandable in its context. Corrective Action: Check the grammatical content of the statement (placement of commas, braces, and so on). Recompile the form specication.

-2019

Description of Error: This integer exceeds the maximum size allowed. Corrective Action: Allowable INTEGER values are whole numbers that range from -2,147,483,647 to 2,147,483,647. Check the value of the number (number of digits and location of the decimal point). If a larger number is required, you will need to use the ALTER TABLE statement to modify the column to DECIMAL type. Recompile the form specication.

-2020

Description of Error: The table table-name could not be opened. The operating system was asked to open it for writing. Corrective Action: Check that you have operating system write permission to create a le in the designated directory. Contact your System Administrator if you need help with this action. Recompile the form specication.

-2021

Description of Error: An illegal color has been specied. Colors 0 through 7 are white, yellow, magenta, red, cyan, green, blue, and black. Corrective Action: See if you misspelled a color name listed in the message. The form specication cannot reference colors by number, nor by names from the colornames le.

-2022

Description of Error: This identier exceeds the maximum length for identiers, which is 50. Corrective Action: Check that all eld names, eld labels, and identiers are less than or equal to 50 characters in length. Recompile the form specication.

-2023

Description of Error: This quoted string exceeds the maximum length for quoted strings, which is 80. Corrective Action: Reduce the number of characters in the quoted string to 80 or less. Recompile the form specication.

-2024

Description of Error: There is already a record record-name specied. If the record-name is the same as a table-name in the form, a default record of the same name is created. Corrective Action: You have already dened a record or a table with the same name. Names of records must be unique.

Error Messages

73

-2025

Description of Error: The comment close symbol ( } ) has been found on line lineno, character charposition, even though no comment has been opened. Corrective Action: Comments must be enclosed within a pair of braces ({ and }). Remove the close comment symbol if it is unnecessary or insert an open comment symbol where appropriate. Recompile the form specication.

-2026

Description of Error: The FORMONLY eld eld-name does not have a type specied. A type must be specied if include lists or default values are specied. Corrective Action: Include a type specication after the eld-name.

-2027

Description of Error: An illegal (invisible, control) character has been found on line lineno, character charposition. It has been replaced by a blank in the listing, but it is still in the source (input) table, and should be removed before attempting to compile again. Corrective Action: Remove the illegal character from the form specication le before attempting the next compile. You can use the following command: od -c form-name This command generates octal code that can help isolate the error. See the UNIX Programmers Manual for more information.

-2028

Description of Error: The symbol symbol-name does not represent a table prex used in this form. It cannot be used here to select record elements. Corrective Action: Check to make sure that the table prexes of all record elements are actual tables in the form.

-2029

Description of Error: Screen record array arrayname has component sizes that either differ from the specied dimension of the array or differ among themselves. Corrective Action: The array size must match the number of components in the screen section.

-2030

Description of Error: A typographical error has been found on line lineno, character charposition. Corrective Action: Edit the form specication le where indicated and correct the error. Recompile the form specication.

-2031

Description of Error: The WORDWRAP attribute can only be specied for CHAR, VARCHAR and TEXT elds. Corrective Action: See if you have specied the wrong eld tag or column name, or the wrong data type of a FORMONLY eld.

74

Error Messages

-2032

Description of Error: The number above could not be successfully converted to either an INTEGER or a DOUBLE or a LONG. Corrective Action: FORM4GL could not convert the number provided. Acceptable LONG values are whole numbers between -2,147,483,647 and 2,147,483,647. Check that the number does not exceed these values (if a xed point number) or that it does not contain an error (if a decimal number). Recompile the form specication.

-2033

Description of Error: The eld eld-name has a default value not within the range of its include list values. Corrective Action: If you have an include list and a default, the default must be within the include list range.

-2035

Description of Error: The WORDWRAP attribute, if specied, should apply to all the columns in a join. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2036

Description of Error: The display lines of a multi-line eld lie in different screen pages. Corrective Action: If the height of your page layout (plus the 4 reserved lines) is taller than the physical screen, or larger than the explicit or default vertical lines dimension in your SCREEN section or command line, FORM4GL divides the form by beginning a new page after the last line that can t on the rst (and subsequent) pages. This happened within your WORDWRAP eld. Correct your form, so that the height of the page layout is no greater than lines - 4. You may need another form to display other elds.

-2037

Description of Error: The PROGRAM attribute can only be specied for BYTE and TEXT elds. Corrective Action: See if you have specied the wrong eld tag or column name, or the wrong data type of a FORMONLY eld.

-2038

Description of Error: BLOB elds cannot be joined. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2039

Description of Error: The attributes AUTONEXT, DEFAULT, INCLUDE, VERIFY, RIGHT and ZEROFILL are not supported for BLOB elds. Corrective Action: Ignore this message. It applies to features of PERFORM forms that 4GL does not support.

Error Messages

75

-2040

Description of Error: The formname form-name exceeds the maximum length of 10 characters. Corrective Action: Check the spelling of form-name. Recompile the form specication.

-2041

Description of Error: The form form-name cannot be opened. This is probably because it does not exist, or the user does not have read permission. Corrective Action: Check the spelling of form-name. Recompile the form specication.

-2042

Description of Error: The usage of a BLOB eld in or around the above statement is incorrect. Corrective Action: You have specied an attribute that does not support
TEXT or BYTE elds, or else your condition for the COLOR attribute cannot be applied to a BLOB.

-2043

Description of Error: Screen layout exceeds the specied screen width. This is a warning only. System Action: Your form successfully compiled. Corrective Action: According to your explicit or default column specication, part of your screen layout lies beyond the right-hand limit of the form or of the physical screen. 4GL programs can use the form, but users may not be able to see part of it. To avoid this effect, use a narrower page layout.

-2044

Description of Error: At most one color attribute may be specied for each eld with each condition. Corrective Action: Correct your ATTRIBUTE section, so that no condition assigns multiple colors to the same eld.

-2045

Description of Error: The conditional attributes of a 4GL eld cannot depend on the values of other elds. Corrective Action: Correct your ATTRIBUTE section, so that no eld tag except that of the current eld appears in the condition.

-2100

Description of Error: Field eld-tag has validation string error, String = character-string Corrective Action: Check that the values in the character string contain only ASCII characters, and represent a value of the appropriate data type.

76

Error Messages

-2800

Description of Error: The rst line of the specication must be the keyword DATABASE followed by the database name, or the FORMONLY keyword (4GL only). An optional WITHOUT NULL INPUT may also follow. Corrective Action: Check the spelling of the rst line of the form specication le, or check that the keyword DATABASE is followed by the database name or the FORMONLY keyword. Recompile the form specication.

-2810

Description of Error: The name database-name is not an existing database name. Corrective Action: Check the spelling of database-name. Check that database-name exists in your current directory or a directory included in your DBPATH environment variable. Recompile the form specication.

-2811

Description of Error: The temporary table table-name could not be opened for writing. Corrective Action: Check that you have operating system write permission to create the le. Contact your System Administrator if you need help with this action. Recompile the form specication.

-2812

Description of Error: The temporary table table-name could not be read. Corrective Action: Check that you have operating system read permission to access the le. Contact your System Administrator if you need help with this action. Recompile the form specication.

-2820

Description of Error: The label name between brackets is incorrectly given or the label is missing. Corrective Action: Check that the eld tag ( = label name) exists and is correctly spelled. Recompile the form specication.

-2830

Description of Error: A left square bracket has been found on this line, with no right bracket to match it. Corrective Action: A set of brackets [ ] is used to delimit the eld size of each eld. Insert a right square bracket ( ] ) where appropriate into the form specication le. Note that a display eld cannot be split across lines. For a multiple-line eld to which you assign the WORDWRAP attribute, each segment must be indicated by delimiters, with the same eld tag repeated in each segment of the eld. Recompile the form specication.

-2831

Description of Error: The control block has exceeded the maximum of 20 elds. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.
Error Messages 77

-2832

Description of Error: This form uses "|" to both start and end a eld placement. Because of this, the form must specify left and right delimiters, which are the same character. This is done with a DELIMITERS command in the INSTRUCTIONS section. Corrective Action: The DELIMITERS section must specify the same 2 characters for the left and right delimiters.

-2834

Description of Error: NULL cannot be used as the default. It is already the default if you specify nothing. Corrective Action: Do not specify NULL for the DEFAULT attribute.

-2840

Description of Error: The label label-name was not dened in the form. Corrective Action: Check that the eld tag label-name is included in both the SCREEN and ATTRIBUTES sections of the form specication le, or delete the unnecessary label-name. (This error often accompanies errors -2820 and -2975.) Recompile the form specication.

-2841

Description of Error: The form must include a tables declaration before the attributes section. Corrective Action: Include a TABLES section before the ATTRIBUTES section.

-2843

Description of Error: The column column-name does not appear in the form specication. Corrective Action: Be sure all elds in the ATTRIBUTES section appear in the
SCREEN section.

-2844

Description of Error: The column column-name is associated with more than one eld in the form specication. Corrective Action: You have specied a record element that appears in more than one eld. Check to see if you need to include a table name in the record element.

-2845

Description of Error: The composite column for table tab-name containing column col-name is not indexed. Performance will be much improved by creating an index on the column. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2846

Description of Error: The eld eld-name is not a member of the table table-name. Corrective Action: Be sure the eld is a column in the specied table.

78

Error Messages

-2850

Description of Error: The name column-name is not a column name in this database. Corrective Action: Check the spelling of the column-name column name. Recompile the form specication.

-2856

Description of Error: The TODAY attribute can be assigned only to date columns. Corrective Action: Check that the eld in which the TODAY keyword has been used is a DATE or DATETIME column. If appropriate, remove the TODAY keyword from the ATTRIBUTES section of the form. Recompile the form specication.

-2859

Description of Error: The column column-name is a member of more than one tableyou must specify the table name. Corrective Action: The column name column-name appears in more than one table used in the form. You must specify the table from which column-name is to be accessed, using the format table-name.column-name. Recompile the form specication.

-2860

Description of Error: There is a column/value type mismatch for column-name. Corrective Action: Check that the value provided as the DEFAULT attribute or listed in the INCLUDE list matches the data type of the column (for example, DATE for a date column, or INTEGER for an integer). Recompile the form specication.

-2861

Description of Error: You have exceeded the maximum of tables. Corrective Action: A maximum of 20 (this number might be larger on some systems) tables can be in use at any one time. Reduce the number of tables included in the form. Recompile the form specication.

-2862

Description of Error: The table table-name cannot be found in the database. Corrective Action: Check the spelling of table-name. Recompile the form specication.

-2863

Description of Error: The column column-name does not exist among the specied tables. Corrective Action: Check the spelling of the column name or check that column-name does exist in one of the specied tables. Recompile the form specication.

Error Messages

79

-2864

Description of Error: The table table-name is not among the specied tables. Corrective Action: Check the spelling of table-name in the ATTRIBUTES section of the le. Check that the table is specied in the TABLES section of your form. Recompile the form specication.

-2865

Description of Error: The column column-name does not exist in the table table-name. Corrective Action: Check the spelling of column-name. Recompile the form specication.

-2866

Description of Error: The NOW attribute may be assigned only to datetime columns. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2867

Description of Error: The CURRENT attribute may be assigned only to datetime columns. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2870

Description of Error: The subscripted column size does not match the space allocated in the display eld. Corrective Action: Check that the space provided in the display eld is greater than or equal to the subscripted column size. Recompile the form specication.

-2880

Description of Error: The word 'screen' or 'end' has been left out. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2890

Description of Error: A screen denition must begin with a left curly bracket {. Corrective Action: Each screen layout must be enclosed within a pair of braces { }. Edit your statement to include the necessary left brace. Note that the left brace must appear in the rst character position on the line. Recompile the form specication.

80

Error Messages

-2892

Description of Error: The column column-name name appears more than once. If you wish a column to be duplicated in a form, use the same display eld label. Corrective Action: The column name column-name appears more than once in the ATTRIBUTES section of the form specication le. Use the same eld tag (in the SCREEN section) to denote the repeated column, and remove any duplicate column names from the ATTRIBUTES section. If you want a multiple-line eld to display long strings on several lines of the form, use the same eld tag in the SCREEN section for each segment of the eld, and assign the WORDWRAP attribute to that eld tag in a single line of the ATTRIBUTES section. Recompile the form specication.

-2893

Description of Error: The display eld label eld-tag appears more than once in this form, but the lengths are different. Corrective Action: A eld tag ( = display eld label) can appear more than once in the SCREEN section, but in every instance the display elds must have identical lengths. Edit the eld delimiters so that they are of equal length. Recompile the form specication.

-2895

Description of Error: Display eld length of number does not match the database column length of number. This is a warning only. Corrective Action: Check that the display eld length (included in the SCREEN section) is equal to the table column size. (This error occurs only in character elds and with the -v option to FORM4GL.)

-2901

Description of Error: Field eld-name contains two conicting attributes, attribute1 and attribute2. Corrective Action: The UPSHIFT and DOWNSHIFT attributes cannot both be assigned to the same eld; nor can NOENTRY and REQUIRED be assigned together, nor NOENTRY and VERIFY.

-2920

Description of Error: The column col-name is a dominant column but it is not indexed. Performance will be much improved by creating an index on the column. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2921

Description of Error: The database database-name is not compatible with the current version of SQL. Corrective Action: The database was created under a prior version of INFORMIX. You must rst convert the database, using sqlconv, before attempting to compile.
Error Messages 81

-2930

Description of Error: Portions of the column column-name are displayed on the screen more than once. Corrective Action: Check the subscripting of column-name (present in the ATTRIBUTES section of the form specication le). Subscripts cannot overlap (for example, [25-49] and [50-75] are acceptable; [25-50] and [50-75] are unacceptable, as character 50 would have to appear twice). Recompile the form specication.

-2931

Description of Error: There is an error in the format specication. Corrective Action: You can only use the FORMAT attribute with a DECIMAL, SMALLFLOAT, FLOAT, or DATE value to control the format of the display. Check the format specications for errors. Recompile the form specication.

-2932

Description of Error: Formats can be specied only for DECIMAL, SMALLFLOAT, FLOAT or DATE columns. Corrective Action: You can only use the FORMAT attribute with a DECIMAL, SMALLFLOAT, FLOAT, or DATE column to control the format of the display. Check that you have not specied the format on a CHAR, DATETIME, INTEGER, INTERVAL, or SMALLINT data type. Recompile the form specication.

-2933

Description of Error: The format width is larger than the allocated display width. Corrective Action: Check that the format of a DECIMAL, SMALLFLOAT, FLOAT, or DATE column matches the length of the display eld in the form. Recompile the form specication.

-2934

Description of Error: The format width is less than the allocated display width. This is a warning only. System Action: The compile was completed. Corrective Action: Check that the format of a DECIMAL, SMALLFLOAT, FLOAT, or DATE column matches the length of the display eld in the form. Note: Until this error is corrected, any data displayed in the eld might be truncated.)

-2935

Description of Error: The number of lines specied with the '-l' option or in the screen section must be a positive integer from 6 to 600. Corrective Action: Your vertical dimension is out of range. Specify a positive value between 6 and (lines - 4), for the number of rows that your physical screen can display.

82

Error Messages

-2936

Description of Error: The number of columns specied with the '-c' option or in the screen section must be a positive integer from 30 to 600. Corrective Action: Your horizontal dimension is out of range. Specify a positive value between 30 and the width (in characters) of your physical screen.

-2940

Description of Error: The column column-name appears both with and without subscripts. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2943

Description of Error: You have exceeded the pseudo machine capacity. Corrective Action: Reduce the complexity and/or number of the instructions in the form. Recompile the form specication.

-2944

Description of Error: You may apply the AFTER ADD, UPDATE, QUERY, or REMOVE commands to a table onlynot a column. Corrective Action: Ignore this message. It applies to features of PERFORM forms that 4GL does not support.

-2945

Description of Error: You may not calculate an aggregate on the display eld eld-name because none of its associated database columns belong to the table table-name. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2946

Description of Error: You may not calculate an aggregate on the displayonly eld eld-name. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2950

Description of Error: The column column-name has no section that starts at 1. Remember that the rst subscript is one, not zero. Corrective Action: Edit the form specication le so that the subscript to the column column-name begins with 1 (and not 0). Recompile the form specication.

-2951

Description of Error: The left and right delimiters must be specied in a two-character string. Corrective Action: When changing the delimiters that INFORMIX-4GL uses to enclose the display elds in the SCREEN section of a form, you must specify both the left and right delimiters with one character each. Recompile the form specication.
Error Messages 83

-2952

Description of Error: In order to use a picture, the picture length must be the same as the display eld length. Corrective Action: Edit the le so that the length of the picture specied with the PICTURE attribute equals the display eld length in the SCREEN section. Recompile the form specication.

-2955

Description of Error: The name eld-tag is not a displayed eld in this form. Corrective Action: The display eld eld-tag has been specied in the ATTRIBUTES section of the form specication le, but the eld-tag is not included in the SCREEN section of the form. Delete the eld-tag from the ATTRIBUTES section or include it in the SCREEN section. Recompile the form specication.

-2958

Description of Error: You may have a maximum of ten parameters in a Cfunction. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2959

Description of Error: Two tables may join with a maximum of integer column pairs, including all components of composite columns. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2970

Description of Error: The column column-name joins with other columns, but it is not indexed. It is recommended that columns be indexed for cross-table queries. Performance will be much improved by creating an index on the column. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2971

Description of Error: This column is not a character column, and therefore cannot be subscripted. Corrective Action: Remove subscripting from any non-CHARACTER columns in your form. Recompile the form specication.

-2972

Description of Error: This column cannot be right justied or zero-lled because its displayed width does not match the actual column width. Corrective Action: Make sure the eld width in the SCREEN section matches the column length.

84

Error Messages

-2973

Description of Error: There may be only one dominant column in a display eld description. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2975

Description of Error: The display eld label eld-tag has not been used. Corrective Action: The eld tag ( = display eld label) eld-tag present in the SCREEN section of the form specication le does not correspond to any eld name in the ATTRIBUTES section. Delete eld-tag from the SCREEN section if it is unnecessary, or else reference it in the ATTRIBUTES section if you have neglected to assign it a name. Recompile the form specication.

-2976

Description of Error: The end of the form has been reached prematurely. Corrective Action: You have a SCREEN section with no following sections. Edit your form specication le to specify any necessary table names or aliases, eld names, non-default screen arrays, or any other required information.

-2977

Description of Error: Table table1 cannot be a master of table table2 because they do not join. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2978

Description of Error: The column col-name1 and the column col-name2 cannot be joined columns because their types or lengths are different. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2984

Description of Error: The table identier table-alias is dened more than once. Corrective Action: Correct the TABLES section, so that each table alias is associated with only one database table.

-2985

Description of Error: The table identiers name and name represent the same table. Corrective Action: Correct the TABLES section, so that each table alias is associated with a different database table.

-2986

Description of Error: The form specication has exceeded the maximum of integer master/detail pairs. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.
Error Messages 85

-2987

Description of Error: The form specication has exceeded the maximum number of screens. Corrective Action: If you specify more than one SCREEN section, each begins a new page of the same form. Similarly, if the height of your page layout (plus the 4 reserved lines) is taller than the physical screen, or larger than the explicit or default vertical lines dimension in your SCREEN section or command line, FORM4GL divides the form by beginning a new page after the last line that can t on the rst (and subsequent) pages. Your form requires more than 20 pages. Redesign and recompile your form, so that the page layout ts on a single page. Use multiple forms or windows, rather than multiple pages, if you need to display more elds.

-2988

Description of Error: FORM4GL has run out of memory. Corrective Action: You have exceeded the data space limit on your machine. Reduce the complexity of the form specication le. Recompile the form specication.

-2989

Description of Error: The column column-name is a reference column, but it is not indexed. It is recommended that reference columns be indexed for lookups. Performance will be much improved by creating an index on the column. Corrective Action: Ignore this message. It applies to features of PERFORM forms that 4GL does not support.

-2991

Description of Error: Warning: Only the rst screen of your multiple-screen form will be displayed under 4GL. System Action: The compilation was successful, but it produced a form with more than one page. Corrective Action: FORM4GL issues this warning because 4GL programs can access a multiple-page form, but cannot properly display any page except the rst. See if you have more than one SCREEN section, or if the page layout exceeds the height limit imposed by the explicit or default lines dimension of your form or of the physical screen. You may have forgotten to allow for the 4 lines required by the system, or reversed the vertical and horizontal specications. (See the description of -2987 for more information.) To avoid concealing display elds, you must redesign and recompile your screen form so that it has only one page. Make the page layout no taller than (lines - 4). Use multiple forms or windows if you need to display more elds than can t on a single page.

86

Error Messages

-2992

Description of Error: The display label eld-tag has already been used. Corrective Action: Each eld tag ( = display label) must be unique. Specify a different eld tag. Recompile the form specication.

-2993

Description of Error: There is a circular join path specied in the form. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2994

Description of Error: The form has exceeded the maximum number of joins between tables. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2995

Description of Error: The form has exceeded the maximum number of tables contained in joins. Corrective Action: Ignore this message. It applies to a feature of PERFORM forms that 4GL does not support.

-2996

Description of Error: The unanticipated error number error-number has occurred. Corrective Action: error-number is an operating system error number. Check the UNIX Programmers Manual for error information relating to error-number. Contact your System Administrator if you need assistance with this action. You might also contact the Technical Support Department of the company that supplied your operating system for advice about this error number. Recompile the form specication.

-2997

Description of Error: See error number errno. Corrective Action: Locate the indicated error message in this appendix. Recompile the form specication.

-2998

Description of Error: Operating system error error-number: string. Corrective Action: If the error number is between 1-99, check your UNIX Programmers Manual for the error corresponding to the number indicated. Contact your System Administrator if you need assistance with this action.

-2999

Description of Error: SQL server terminated. Corrective Action: You may have killed the engine daemon by accidentally killing the wrong process, or an internal error may have overwritten a pipe to the engine. After verifying that the error is not the result of a system limit or problem, please notify the Informix Technical Support Department.
Error Messages 87

-4300

Description of Error: This statement contains too many levels of function call nesting. Corrective Action: A CALL statement can contain only four levels of nested functions. Reduce the number of nested functions in your CALL statement so that it does not exceed four.

-4301

Description of Error: The program has too many levels of WHILE, FOR, MENU, and/or CASE statements. Corrective Action: A program can contain only 25 levels of WHILE, FOR, MENU, and/or CASE statements (in any combination). Reduce the number of nested WHILE, FOR, MENU, and/or CASE statements so that it does not exceed 25.

-4302

Description of Error: The record description is nested too deep. Corrective Action: Only ve levels of nested records can appear in a record denition. Reduce the number of nested records so that it does not exceed ve.

-4304

Description of Error: A different database has already been declared. If your program uses a global denition le, it must contain the same database name as this one. Corrective Action: Make sure that the database specied in a global denition le is the same as the database specied in the le containing the MAIN routine.

-4305

Description of Error: The database database-name cannot be found or opened. If the database exists, check the database permissions on the database. In addition, check the system permissions on the database directory and its ascendant directories. Corrective Action: Check the spelling of the database name. Check that the database name exists in your current directory or in a directory included in your DBPATH environment variable. Make sure that you have at least CONNECT permission for the database as well as the appropriate operating system permissions for the database directory.

-4306

Description of Error: The GLOBALS le lename cannot be opened for reading. Corrective Action: Check that the GLOBALS le exists and that you have operating system read permission for the le. If the GLOBALS le is not in the current directory, you must specify the pathname of the le from root or current directory.

88

Error Messages

-4307

Description of Error: The number of variables and/or constants in the display list does not match the number of form elds in the display destination. Corrective Action: Check the variable-list and the eld-list in your DISPLAY or DISPLAY ARRAY statement to make sure that they contain the same number of items.

-4308

Description of Error: The number of input variables does not match the number of form elds in the screen input list. Corrective Action: Check the variable-list and the eld-list in your INPUT or INPUT ARRAY statement to make sure that they contain the same number of items.

-4309

Description of Error: Printing cannot be done within a loop or CASE statement contained in report headers or trailers. Corrective Action: Do not include PRINT statements within FOR, WHILE, or CASE statements that appear in FIRST PAGE HEADER, PAGE HEADER, and PAGE TRAILER control blocks.

-4310

Description of Error: Files cannot be printed within report headers or trailers. Corrective Action: Do not include PRINT FILE statements within FIRST PAGE HEADER, PAGE HEADER, and PAGE TRAILER control blocks.

-4311

Description of Error: The variable variable-name was not dened as a record. It cannot be used in this fashion. Corrective Action: You can use the THRU, THROUGH, or .* notations only with records. Dene the variable as a record or remove the THRU, THROUGH, or .* notation, as appropriate.

-4312

Description of Error: The NEED statement is allowed only within reports. Corrective Action: Make sure that the NEED statement only occurs within the FORMAT section of a report.

-4313

Description of Error: The NEED statement cannot be used within report headers or trailers. Corrective Action: Remove any NEED statements from FIRST PAGE HEADER, PAGE HEADER, and PAGE TRAILER control blocks.

-4314

Description of Error: The program cannot exit a menu at this point because it is not within a MENU statement. Corrective Action: Make sure that the EXIT MENU keywords appear only within a COMMAND clause of the MENU statement.
Error Messages 89

-4315

Description of Error: The program cannot exit a FOREACH statement at this point because it is not within a FOREACH statement. Corrective Action: Make sure that the EXIT FOREACH keywords appear only within a FOREACH statement.

-4316

Description of Error: The program cannot exit a WHILE statement at this point because it is not within a WHILE statement. Corrective Action: Make sure that the EXIT WHILE keywords appear only within a WHILE statement.

-4317

Description of Error: The program cannot exit a FOR statement at this point because it is not within a FOR statement. Corrective Action: Make sure that the EXIT FOR keywords appear only within a FOR statement.

-4318

Description of Error: The program cannot exit a CASE statement at this point because it is not within a CASE statement. Corrective Action: Make sure that the EXIT CASE keywords appear only within a CASE statement.

-4319

Description of Error: The symbol variable-name has been dened more than once. Corrective Action: Make sure that each variable is dened only once in your GLOBALS, MAIN, FUNCTION, or REPORT statement.

-4320

Description of Error: The symbol table-name is not the name of a table in the specied database. Corrective Action: Check the spelling of table-name and make sure that it is a table in the specied database.

-4321

Description of Error: An array may have the maximum of three dimensions. Corrective Action: Make sure that the array has no more than three dimensions.

-4322

Description of Error: The symbol column-name is not the name of a column in the specied database. Corrective Action: Check the spelling of column-name, and make sure that it appears in a table of the specied database.

90

Error Messages

-4323

Description of Error: The variable variable-name is too complex a type to be used in an assignment statement. Corrective Action: You can assign a value only to a variable that has a simple type. If you are assigning a value to an element of an array or record, make sure that it has a simple type.

-4324

Description of Error: The variable variable-name is not a character type, and cannot be used to contain the result of concatenation. Corrective Action: Change the data type of the variable to CHAR so that it can store the string that results from concatenation.

-4325

Description of Error: The source and destination records in this record assignment statement are not compatible in types and/or lengths. Corrective Action: In the statement LET a.* = b.*, each element in record a must have a data type which is compatible with the data type of the corresponding element in record b.

-4326

Description of Error: A NULL value may not be applied to substrings. Corrective Action: A NULL value can be assigned to a string but not to a substring. Remove the subscript(s) if you want to assign a NULL value to the string.

-4327

Description of Error: The variable variable-name is not of type INTEGER or SMALLINT. It cannot be used as a loop index. Corrective Action: Change the type of the variable to INTEGER or SMALLINT if you want to use it as a loop index.

-4328

Description of Error: The variable variable-name has too complex a type to be used as the destination of a return from a function. Corrective Action: You must return values to variables that have simple types. If you have specied a record in the RETURNING clause of a CALL statement, remember to include the THRU, THROUGH, or .* shorthand after the record name, and make sure that all the record elements referenced in this way have simple types.

-4329

Description of Error: The variable variable-name is not a record. Only record variables may be expanded using the .* or THROUGH shorthand. Corrective Action: Change the variable to a record or eliminate the THROUGH, THRU, or .* notation as appropriate.

Error Messages

91

-4330

Description of Error: RETURN statements can be executed only within functions. Corrective Action: Make sure that the RETURN keyword appears only within a FUNCTION statement.

-4331

Description of Error: Only variables of type INTEGER or SMALLINT may be used to index display elds. Corrective Action: Change the type of the variable to INTEGER or SMALLINT if you want to use it to index display elds.

-4332

Description of Error: The LET statement must have at least one source expression. Corrective Action: Make sure that one or more valid expressions appears to the right of the equal sign (=) in a LET statement.

-4333

Description of Error: The function function-name has already been called with a different number of parameters. Corrective Action: Make sure that you specify the same number of parameters each time you call a function.

-4334

Description of Error: The variable variable-name in its current form is too complex to be used in this statement. Corrective Action: You can use only variables that have simple types. If you have specied a record in the statement, remember to include the THRU, THROUGH, or .* shorthand after the record name, and make sure that all the record elements referenced in this way have simple types.

-4335

Description of Error: The symbol variable-name is not an element of the record record-name. Corrective Action: Make sure that the variable is listed as an element of the record in the appropriate DEFINE statement.

-4336

Description of Error: The parameter variable-name has not been dened within the function or report. Corrective Action: You must use the DEFINE statement to declare all parameters passed as arguments to a function or report.

-4338

Description of Error: The symbol variable-name has already been dened once as a parameter. Corrective Action: Make sure that each parameter is dened only once in a function or report.

92

Error Messages

-4339

Description of Error: 4GL has run out of data space memory. System Action: The program stops and running transactions are rolled back. Corrective Action: Divide your program into smaller modules, or reduce the complexity of the program.

-4340

Description of Error: The variable variable-name is too complex a type to be used in an expression. Corrective Action: You can use only variables that have simple types in expressions. If you have specied an element of a record or array, make sure that it has a simple type.

-4341

Description of Error: Aggregate functions are only allowed in reports and SELECT statements. Corrective Action: You can use aggregate functions like SUM and AVG only in reports and in expressions that appear in SELECT statements.

-4342

Description of Error: PAGENO and LINENO are allowed only in reports. Corrective Action: Make sure that the PAGENO and LINENO statements only occur within the FORMAT section of a report.

-4343

Description of Error: Subscripting cannot be applied to the variable variable-name because it is not a character or array variable. Corrective Action: Check the spelling of the variable name. Dene variable-name as a character or array variable or remove the subscript, as appropriate.

-4344

Description of Error: The variable variable-name cannot be used with substrings because it is not a character variable. Corrective Action: Check the data type of the variable. If variable-name is not a character variable, remove the subscript(s) or change the type of the variable, as appropriate.

-4345

Description of Error: The variable variable-name has already had substrings applied to it. Corrective Action: Rewrite the statement so that only one substring (represented by the notation [a, b]) appears after the variable name.

Error Messages

93

-4346

Description of Error: Subscripts may contain only INTEGER or SMALLINT variables. Corrective Action: Check the spelling of the variable name(s). Make sure that each variable is dened as an INTEGER or SMALLINT if you want to use it as a subscript.

-4347

Description of Error: The variable variable-name is not a record. It cannot reference record elements. Corrective Action: Check the spelling of the variable name. Make sure that the variable is dened as a record before you add a sufx (.variable-name) to it.

-4348

Description of Error: This type of aggregate must be applied to an expression, not *. Only PERCENT and COUNT aggregates use *. Corrective Action: Use an expression instead of an asterisk (*) with the SUM, AVG, MIN, and MAX aggregates.

-4349

Description of Error: The PERCENT and COUNT report aggregates cannot be used with an expression. Corrective Action: Use an asterisk (*) instead of an expression with the PERCENT and COUNT aggregates.

-4350

Description of Error: The program cannot continue a FOR loop at this time because it is not within a FOR loop. Corrective Action: Make sure that the CONTINUE FOR keywords appear only within a FOR statement.

-4351

Description of Error: The program cannot continue a WHILE loop at this time because it is not within a WHILE loop. Corrective Action: Make sure that the CONTINUE WHILE keywords appear only within a WHILE statement.

-4352

Description of Error: The program cannot continue a FOREACH loop at this time because it is not within a FOREACH loop. Corrective Action: Make sure that the CONTINUE FOREACH keywords appear only within a FOREACH statement.

-4356

Description of Error: A page header has already been specied within this report. Corrective Action: Change the FORMAT section of your report so that it contains only one PAGE HEADER control block.

94

Error Messages

-4357

Description of Error: A page trailer has already been specied within this report. Corrective Action: Change the FORMAT section of your report so that it contains only one PAGE TRAILER control block.

-4358

Description of Error: A rst page header has already been specied within this report. Corrective Action: Change the FORMAT section of your report so that it contains only one FIRST PAGE HEADER control block.

-4359

Description of Error: An ON EVERY ROW clause has already been specied within this report. Corrective Action: Change the FORMAT section of your report so that it contains only one ON EVERY ROW control block.

-4360

Description of Error: An ON LAST ROW clause has already been specied within this report. Corrective Action: Change the FORMAT section of your report so that it contains only one ON LAST ROW control block.

-4361

Description of Error: Group aggregates can occur only in AFTER GROUP clauses. Corrective Action: Make sure that the GROUP COUNT, GROUP PERCENT, GROUP SUM, GROUP AVG, GROUP MIN, and GROUP MAX aggregates appear only in AFTER GROUP control blocks.

-4362

Description of Error: The report cannot skip to the top of page while in a header or trailer. Corrective Action: Remove SKIP TO TOP OF PAGE statements from FIRST PAGE HEADER, PAGE HEADER, and PAGE TRAILER control blocks.

-4363

Description of Error: The report cannot skip lines while in a loop within a header or trailer. Corrective Action: Remove SKIP statements from FOR and WHILE loops that appear in FIRST PAGE HEADER, PAGE HEADER, and PAGE TRAILER control blocks.

-4364

Description of Error: There are a non-matching number of variables and database columns in this statement. Corrective Action: Make sure that the number of variables in the statement is the same as the number of database columns.
Error Messages 95

-4365

Description of Error: Deferments of interrupt or quit may be executed only in the main program. Corrective Action: Make sure that DEFER INTERRUPT and DEFER QUIT statements appear only in the MAIN section of your program.

-4366

Description of Error: There are a non-matching number of variables and database columns in this statement. Corrective Action: Make sure that the number of variables in the statement is the same as the number of database columns.

-4367

Description of Error: Interrupt has already been deferred once in the MAIN program. Each main program may defer interrupt only once. Corrective Action: Make sure that the DEFER INTERRUPT statement appears only once, and then only in the MAIN section of your program. (Once deferred, Interrupt signals cannot be reactivated.)

-4368

Description of Error: Quit has already been deferred once in the MAIN section of your program. Each main program may defer quit only once. Corrective Action: Make sure that the DEFER QUIT statement appears only once, and then only in the MAIN section of your program. (Once deferred, Quit signals cannot be reactivated.)

-4369

Description of Error: The symbol variable-name does not represent a dened variable. Corrective Action: Make sure that you dene the variable in a DEFINE statement in the appropriate part of your program.

-4370

Description of Error: The variable variable-name cannot be used in validation. Corrective Action: You can validate only variables that have simple types. If you have specied a record in the statement, remember to include the THRU, THROUGH, or .* notation after the record name, and make sure that all record elements referenced in this way have simple types.

-4371

Description of Error: Cursors must be uniquely declared within one program module. Corrective Action: Make sure that each cursor is declared only once in a program le.

96

Error Messages

-4372

Description of Error: The cursor cursor-name has not yet been declared in this program module. It must be declared before it can be used. Corrective Action: You must use the DECLARE statement to declare a cursor in each module before you can use it in statements such as FOREACH, OPEN, and FETCH.

-4373

Description of Error: A grammatical error has been found on line line-number, character character-number. The construct is not understandable in its context. Corrective Action: When INFORMIX-4GL encounters a grammatical error, it inserts a marker in the .err le just past the point where the parser detected the error. Check the syntax of the marked statement.

-4375

Description of Error: The page length is too short to cover the specied page header and trailer lengths. Corrective Action: Make sure that the total number of lines required for the page header and trailer do not exceed the default page length or the length specied in the PAGE LENGTH statement. Change the page header and trailer or the page length as appropriate.

-4376

Description of Error: The temporary le lename cannot be created for writing. Corrective Action: Check that you have permission to write a le in /tmp or the directory specied by the DBTEMP environment variable. Check that there is enough space in the directory where the temporary le will reside. Contact your System Administrator if you need help with these actions.

-4377

Description of Error: The output le lename cannot be created or opened. Corrective Action: Check that you have permission to write a le in the directory where the output le will be created. Contact your System Administrator if you need help with this action.

-4378

Description of Error: No input le was specied. Corrective Action: Make sure that you specify an input lename.

-4379

Description of Error: The input le lename cannot be opened. Corrective Action: Check the spelling of the input lename. Check that the le exists in the current directory. Check that you have operating system read permission for the input le.

Error Messages

97

-4380

Description of Error: The listing le lename cannot be created. Corrective Action: Check that you have operating system write permission in the directory where the listing le will be created. Contact your System Administrator if you need help with this action.

-4381

Description of Error: The input le lename has an invalid extension. The lename must have .4gl as the extension. Corrective Action: Rename the input le so that it has the extension .4gl.

-4382

Description of Error: Record variables that contain array type elements may not be referenced by the ".*" or THROUGH shorthand, or used as a function parameter. Corrective Action: Rewrite your statement so that record variables with array components do not appear with the THRU, THROUGH, or .* shorthands or as function parameters.

-4383

Description of Error: The elements element-name1 and element-name2 do not belong to the same parent record. Corrective Action: Check the spelling of the element names and make sure that both elements belong to the same record.

-4384

Description of Error: The symbol element-name does not represent the element of any record. Corrective Action: Check the spelling of element-name and make sure that it belongs to the specied record.

-4385

Description of Error: Report aggregates may not be nested. Corrective Action: Rewrite your statement so that report aggregates are not nested.

-4386

Description of Error: There are too many ORDER BY elds in this report. The maximum number is eight. Corrective Action: Reduce the number of ORDER BY elds to eight or less.

-4387

Description of Error: The right margin must be greater than the left margin. Corrective Action: Check that the RIGHT MARGIN value is greater than the LEFT MARGIN value.

98

Error Messages

-4388

Description of Error: There is one BEFORE GROUP OF clause and one AFTER GROUP OF clause allowed for each report input parameter. Corrective Action: You can use only one BEFORE GROUP OF control block and one AFTER GROUP OF control block for each report parameter. You must combine multiple BEFORE GROUP OF or AFTER GROUP OF control blocks for the same parameter into a single control block.

-4389

Description of Error: There are too many levels of nesting of IF statements in this report. Corrective Action: You have exceeded the maximum of ve levels of nested IF statements. Remove one or more statements.

-4391

Description of Error: When doing INPUT BY NAME or INPUT ARRAY, the BEFORE/AFTER eld names can be specied only by the eld name sufx. Screen array and screen record elements are not allowed. Corrective Action: You cannot include a prex when specifying a eld name in a BEFORE FIELD or AFTER FIELD clause of an INPUT or INPUT ARRAY statement. (A prex consists of table-name, formonly, screen-record, or screen-record[n] followed by a period.)

-4392

Description of Error: The 4GL compiler has run out of data space memory to contain the 4GL program symbols. If the program module is very large, dividing it into separate modules may alleviate the situation. Corrective Action: Divide your program into smaller programs or reduce the complexity of your program.

-4393

Description of Error: The MENU statement has exceeded the maximum number of selections. Corrective Action: Reduce the number of COMMAND clauses in the MENU statement so that it does not exceed the limit of 25.

-4394

Description of Error: The MENU statement has two or more selections using the key-name key. Corrective Action: The user selects a menu option by typing one of the letters in a key list (if a KEY clause for the menu option is present) or by typing the rst letter of the menu option (if a KEY clause for the option is not present). Rewrite the MENU statement so that the letter for selecting each menu option is unique.

Error Messages

99

-4395

Description of Error: There are too many subscripts specied with a database column name. Corrective Action: You can use no more than two subscripts with database columns of type CHAR.

-4396

Description of Error: The MENU declaration at line lineno is not terminated. Corrective Action: Make sure that you conclude the MENU statement with the END MENU keywords.

-4397

Description of Error: The IF statement at line lineno is not terminated. Corrective Action: Make sure that you conclude the IF statement with the END IF keywords.

-4398

Description of Error: The CASE statement at line lineno is not terminated. Corrective Action: Make sure that you conclude the CASE statement with the END CASE keywords.

-4399

Description of Error: The WHILE statement at line lineno is not terminated. Corrective Action: Make sure that you conclude the WHILE statement with the END WHILE keywords.

-4400

Description of Error: The FOR statement at line lineno is not terminated. Corrective Action: Make sure that you conclude the FOR statement with the END FOR keywords.

-4401

Description of Error: A concatenation operation has created a string too long to t in the destination string variable. Corrective Action: When possible, use the CLIPPED keyword to eliminate trailing blanks from the strings you want to concatenate. If the resultant string still exceeds the length of the character variable, increase the size of the character variable.

-4402

Description of Error: In this type of statement, subscripting may be applied only to array variables to select individual array elements. Corrective Action: Make sure that the variable is dened as an array before you use it with subscripts in this type of statement.

100

Error Messages

-4403

Description of Error: The number of dimensions for the variable variable-name does not match the number of subscripts. Corrective Action: Rewrite the statement so that the number of subscripts after the array name is the same as the number of dimensions in the array denition.

-4406

Description of Error: There is an unmatched quote in the above line. Corrective Action: Check that all strings begin and end with a quote.

-4407

Description of Error: There is an unprintable character in the above line. Corrective Action: Remove the unprintable character (usually a control character). You may have to retype the line.

-4408

Description of Error: There is a quoted string that is too long in the above line. Corrective Action: A quoted string cannot exceed 80 characters. Reduce the length of the quoted string or, if appropriate, divide it into shorter strings separated by commas.

-4409

Description of Error: There is an invalid character in the above line. Corrective Action: Remove the invalid character (often a non-printable control character).

-4410

Description of Error: There is a numeric constant in the previous line that is too large or too small. Corrective Action: Make sure that the number has no more than 50 characters, and that it is within the acceptable range for its data type. For SMALLINT values, this range is from -32,767 to -32,767. An INTEGER must have an absolute value in the range from zero to 2,147,483,647. The absolute value of a DECIMAL number can range from from 10-128 to 10126. Also check that you have not inadvertently entered a letter in place of a digit.

-4411

Description of Error: There is an alphanumeric identier that is too long in the above line. Corrective Action: Make sure that an alphanumeric identier is no longer than 50 characters.

-4412

Description of Error: Values from the RUN command can be returned only to INTEGER or SMALLINT variables. Corrective Action: Make sure that the variables that appear in the RETURNING clause of a RUN statement are dened as INTEGER or SMALLINT.
Error Messages 101

-4413

Description of Error: The label label-name has already been dened within this MAIN program or function. Corrective Action: Make sure that each label is dened only once in the MAIN program or function.

-4414

Description of Error: The label label-name has been used but has never been dened within the above main program or function. Corrective Action: Make sure that you dene each label with the LABEL statement before using it in the MAIN program or function.

-4415

Description of Error: An ORDER BY or GROUP item specied within a report must be one of the report parameters. Corrective Action: Make sure that only report parameters appear in ORDER BY, BEFORE GROUP OF, or AFTER GROUP OF statements in a report. You cannot use global or local variables.

-4416

Description of Error: There is an error in the validation string: string. Corrective Action: Change the appropriate DEFAULT or INCLUDE value in the syscolval table.

-4417

Description of Error: This type of statement can be used only in a report. Corrective Action: Make sure that statements like PRINT, SKIP, and NEED appear only in a REPORT statement.

-4418

Description of Error: The variable used in the INPUT ARRAY statement must be an array. Corrective Action: Check the spelling of the variable name and make sure that it has been dened as an array.

-4419

Description of Error: The variable used in the CONSTRUCT statement must be a character variable. Corrective Action: Make sure that the variable that appears after the
CONSTRUCT keyword has been dened as a large CHAR variable.

-4420

Description of Error: The number of lines printed in the IF part of an IFTHEN-ELSE statement of a header or trailer clause must equal the number of lines printed in the ELSE part. Corrective Action: Add or remove lines as necessary so that number of lines printed in the IF part is the same as the number of lines printed in the ELSE part of the IF-THEN-ELSE statement.

102

Error Messages

-4421

Description of Error: You may not use an INPUT statement within another INPUT statement or PROMPT statement, even if it is enclosed within a conditional or looping statement. Corrective Action: Remove any INPUT statements that appear within an INPUT or PROMPT statement.

-4422

Description of Error: You may not use a CONSTRUCT statement within another INPUT statement. This includes situations when CONSTRUCT is enclosed within a conditional or looping statement. You must call a function that executes the CONSTRUCT statement. Corrective Action: Move any CONSTRUCT statement within an INPUT statement to a function, and call that function from the INPUT statement.

-4423

Description of Error: The CLIPPED and USING options for the DISPLAY statement may not be used when displaying to a form eld. Corrective Action: Remove all references to CLIPPED and USING from DISPLAY TO or DISPLAY BY NAME statements. You can substitute for USING an appropriate format string with the FORMAT attribute, and recompile the form.

-4424

Description of Error: The variable variable-name has not been dened as a record. Corrective Action: Make sure that the variable is dened as a record before using it with the THRU, THROUGH, or .* notation.

-4425

Description of Error: The variable variable-name has not been dened LIKE the table table-name. Corrective Action: Dene the variable with the RECORD LIKE keywords if you want to use it in an UPDATE statement.

-4426

Description of Error: The PRINT statement may be used only within reports. If you wish to print without screen positioning, use the DISPLAY statement without any eld or screen destination. Corrective Action: Replace all PRINT statements that appear outside of reports with DISPLAY statements. Use the DISPLAY TO or DISPLAY BY NAME statement to display information in a display eld on a screen form, the DISPLAY AT statement to display information at a specied row and column on the screen, or the DISPLAY statement to display information without screen positioning.

Error Messages

103

-4427

Description of Error: The COLUMN feature for the DISPLAY statement may be used only when displaying without screen or eld destination. Corrective Action: Remove the COLUMN function from the display list of any DISPLAY AT, DISPLAY TO, or DISPLAY BY NAME statement.

-4428

Description of Error: You may not use a PROMPT statement within an INPUT or PROMPT statement, even if it is enclosed within a conditional or looping statement. Corrective Action: Remove any PROMPT statements that appear within an INPUT or PROMPT statement.

-4429

Description of Error: Report and function parameters cannot be arrays. Corrective Action: Remove any arrays from the parameter lists of functions or reports.

-4430

Description of Error: Record parameters for a report cannot contain elements that are arrays. Corrective Action: Rewrite your program so that record parameters for reports do not contain array elements.

-4432

Description of Error: An element in a GROUP clause must be a member of the ORDER BY clause. Corrective Action: Rewrite the statement so that each element in a BEFORE GROUP OF or AFTER GROUP OF clause also appears in the ORDER BY clause.

-4433

Description of Error: A variable used in the above statement must be of type CHAR. Corrective Action: The lename in the REPORT TO lename statement must evaluate to a CHAR variable, or the program in the REPORT TO PIPE program statement must evaluate to a CHAR variable.

-4434

Description of Error: The limits of the INFORMIX-4GL Demo Version have been exceeded. Please call Informix Software, Inc. at (415) 926-6300 for licensing information. Corrective Action: A program compiled using the demonstration version of INFORMIX-4GL can contain only one module with no more than 150 INFORMIX-4GL statements. Check that you have not exceeded the statement limit or called a function that is not included in the module. Please contact your Informix Sales Representative for information about a full INFORMIX-4GL development license.

104

Error Messages

-4435

Description of Error: An acceptable hyphenated key format is control-x, where x is any letter except a, d, h, l, r, or x. Corrective Action: You cannot redene a function key as one of the editing keys for an INPUT, INPUT ARRAY, or CONSTRUCT statement. Select an alternate key.

-4437

Description of Error: All table names in the SELECT list must be the same as the table names in the FROM clause. Corrective Action: Check that you have not misspelled the name of a table in the SELECT list.

-4438

Description of Error: You cannot SELECT into a substring of a character variable. Corrective Action: Remove the substring from the CHAR variable in the INTO clause of the SELECT statement.

-4439

Description of Error: You cannot SELECT into record record-name because element element is a record or an array. Corrective Action: Edit the SELECT statement in your program.

-4440

Description of Error: element-name precedes element-name in record record-name and must also precede it when used with the THROUGH shorthand. Corrective Action: Re-order the elements used with the THROUGH keyword to match the order of elements in the record.

-4441

Description of Error: The ISAM cursor cursor-name has not yet been declared in this program module. It must be declared before it can be used. Corrective Action: Check the spelling of cursor_name and that you have physically declared the cursor before making reference to it.

-4442

Description of Error: fetch-direction is not a recognized row selector in the ISAM FETCH statement. Corrective Action: fetch-direction must evaluate to one of the following: FIRST, LAST, CURRENT, RELATIVE integer, ABSOLUTE integer, NEXT, PRIOR, PREVIOUS, or ROWID integer. Check the spelling of fetch-direction.

-4443

Description of Error: Only constants and variables of type INTEGER or SMALLINT may be used to specify the size and/or position of windows. Corrective Action: Check that the values in the WITH and AT clauses of the OPEN WINDOW statement evaluate to type INTEGER or SMALLINT.
Error Messages 105

-4444

Description of Error: Too many colors specied for window. Corrective Action: You can include only one color in the ATTRIBUTE clause of the OPEN WINDOW statement.

-4445

Description of Error: You may not open or close window SCREEN. Corrective Action: You cannot execute an OPEN WINDOW screen or CLOSE WINDOW screen statement. Edit your INFORMIX-4GL program.

-4446

Description of Error: Key value key-value may not be used in this context. Corrective Action: Choose an acceptable key value and recompile the program. Acceptable key values are f1 through f36, ESC, ESCAPE, the Interrupt key, or CTRL-k where k is any character except a, d, h, l, r, or x. Some systems also reserve CTRL-S and CTRL-Q for special purposes.

-4447

Description of Error: Value is not a recognized key value. Corrective Action: Choose an acceptable key value and recompile the program. Acceptable key values are f1 through f36, ESC, ESCAPE, the Interrupt key, or CTRL-X where x is any character except a, d, h, l, r, or x.

-4448

Description of Error: Cannot open the le lename for reading or writing. Corrective Action: Check that the le lename exists and that you have permission to read or write to it.

-4452

Description of Error: The function function-name has already been dened. Corrective Action: Check your code to make sure that the function has not been dened more than once. Recompile the program.

-4453

Description of Error: The size of the global string table has exceeded the limit of 32767. Corrective Action: Reduce the number of global variables or reduce the length of each global variable and recompile the program.

-4454

Description of Error: The size of the local string table has exceeded the limit of 32767. Corrective Action: Decrease the length or the number of strings and local variables. Recompile the program.

-4456

Description of Error: This help number is not acceptable or reserved. Corrective Action: Use help numbers in the range -32,767 to 32,767.

106

Error Messages

-4457

Description of Error: You may have at most 4 keys in the key list. Corrective Action: Reduce the number of keys to four or less when using the Key clause in the COMMAND statement of MENU.

-4458

Description of Error: One dimension of this array has exceeded the limit of 32767. Corrective Action: Split the array so that the maximum dimension of the array is less than 32,767. Recompile the form specication.

-4459

Description of Error: The total size of an array cannot exceed num. Corrective Action: Decrease the size of the array to the hardware limit specied by num and recompile the form specication.

-4460

Description of Error: Invalid attribute name string. Corrective Action: Check the spelling of the attribute name. Allowable attribute names are WHITE, YELLOW, MAGENTA, RED, CYAN, GREEN, BLUE, BLACK, REVERSE, BLINK, UNDERLINE, and those that have been added to the colornames le. Correct the attribute statement and recompile the program.

-4461

Description of Error: Line num in the colornames le must have the form "<color> 0-9". Corrective Action: The compiler cannot read the colornames le located in either the current directory or $INFORMIXDIR/incl because a line does not have the specied format. Check the spelling and syntax for line num in the colornames le and recompile the program.

-4462

Description of Error: Scroll direction must be either UP or DOWN. Corrective Action: Check the spelling of the scroll direction.

-4463

Description of Error: You may not use NEXT FIELD outside of an INPUT statement. Corrective Action: Place NEXT FIELD inside an INPUT statement or INPUT ARRAY statement and recompile.

-4464

Description of Error: The number of columns must match the number of values in the SET clause of an UPDATE statement. Corrective Action: Make sure that the SET clause includes as many columns in the column-list as the number of values that are produced by the expr-list.

Error Messages

107

-4465

Description of Error: The FOREACH statement at line num is not terminated. Corrective Action: Make sure that each FOREACH keyword is eventually followed by a corresponding END FOREACH keyword that terminates the FOREACH loop. EXIT FOREACH is not equivalent to END FOREACH.

-4466

Description of Error: Column column-name of table table-name has too many default values. Corrective Action: Only one default value is allowed for a column. While compiling the INITIALIZE LIKE statement, the compiler has found more than 1 default value for the specied column. These defaults are put into the syscolval table by the upscol utility. Use the upscol utility to remove all but one of the values and recompile the program.

-4467

Description of Error: Array array-name must have just 1 dimension for INPUT ARRAY or DISPLAY ARRAY. Corrective Action: Check that the array specied in the INPUT ARRAY or DISPLAY ARRAY statement has only one dimension. Remove all other dimensions and recompile the program.

-4468

Description of Error: Column column-name does not belong to table table-name. Corrective Action: Check the spelling of column column-name. Check that column column-name is located in the database table.

-4469

Description of Error: FOR UPDATE cannot be used with SCROLL cursors. Corrective Action: Do not DECLARE a SCROLL cursor with a FOR UPDATE clause.

-4470

Description of Error: A SCROLL cursor was not declared. Corrective Action: Do not use a FETCH direction statement where direction is anything other than a NEXT with a non-scrolling cursor. Declare the cursor as a SCROLL cursor to FETCH FIRST, FETCH PREVIOUS, etc.

-4471

Description of Error: UPDATEs may not be used with singleton selects. Corrective Action: Remove the FOR UPDATE clause and recompile, or DECLARE a cursor for UPDATE with a WHERE CURRENT OF clause or use the cursor instead.

-4472

Description of Error: The INPUT statement at line num is not terminated. Corrective Action: Add an END INPUT statement to match the specied INPUT statement.

108

Error Messages

-4473

Description of Error: The DISPLAY ARRAY statement at line num is not terminated. Corrective Action: Add an END DISPLAY statement to match the specied DISPLAY statement.

-4474

Description of Error: The PROMPT statement at line num is not terminated. Corrective Action: Add an END PROMPT statement to match the specied PROMPT statement.

-4475

Description of Error: name may not be used as both a function name and a variable name. Corrective Action: Rename either the function or the variable, and recompile the program.

-4476

Description of Error: Record members may not be used with database column substring. Possible misspelling or usage of undened host variables. Corrective Action: This statement uses an expression of the form name1.name2[...], where name2 is either a column name, in which case you cannot specify the substring, or else a variable that has not been dened. Check the spelling of name1.name2, or remove the brackets, and recompile the program.

-4477

Description of Error: The variable variable-name is an array. You must specify one of its elements in this statement. Corrective Action: Use subscripts to specify an element, and recompile the program. Make sure that you specify only one element of the array with the notation array-name [element-number]. Do not specify the entire array.

-4478

Description of Error: The size of the local variables used in this function has exceeded the 32K per function limit. Corrective Action: Reduce the size of the functions local variables, and recompile.

-4479

Description of Error: Warning: non-ANSI comment indicator. Use -- for ANSI compatibility. Corrective Action: If you want your source code to conform to ANSI Level I standards for SQL, substitute -- for the braces ( { } ) or pound ( # ) symbol comment indicator.

Error Messages

109

-4480

Description of Error: Warning: this statement is not compatible with ANSI Standard SQL syntax. Corrective Action: The statement is an extension to the ANSI standard for SQL. If you want your source code to conform to ANSI standards for SQL, you must edit and recompile your source code to include only ANSI statements. See Chapter 7 of this manual for a list of the Informix extensions to the ANSI standard syntax for SQL.

-4481

Description of Error: Subscripting cannot be applied to the variable name because it is not an array variable. The substring operator cannot be used with host variables in this statement. Corrective Action: Check that name is spelled correctly. Delete any subscripts of non-array variables, and recompile.

-4482

Description of Error: BY NAME may not be used with owner names or remote database names. Corrective Action: The name of a eld in a screen form cannot be qualied by an owner name, a site name, or a remote database name. In the TABLES section of the form specication le, specify a table alias that includes the qualier(s). Use this alias in the BY NAME clause of any 4GL statements that reference elds linked to columns of the table. Then recompile your form and your program.

-4483

Description of Error: No more than two subscripts may be used to specify a substring. Corrective Action: Delete the extraneous subscript(s), and recompile.

-4484

Description of Error: Cannot specify UNIQUE CONSTRAINT name for TEMP table. Corrective Action: You can specify a UNIQUE CONSTRAINT for a TEMP table, but you cannot specify a name for the constraint. Remove the CONSTRAINT constr-name clause from your CREATE TEMP TABLE statement.

-4501

Description of Error: A parameter count mismatch has occurred between the calling function and the called function. Corrective Action: Make sure that the number of parameters in the calling statement is the same as the number of parameters in the called function.

110

Error Messages

-4502

Description of Error: The 4GL program has run out of runtime data space memory. System Action: The program stops and running transactions are rolled back. Corrective Action: Divide your program into smaller modules. Reduce the size of arrays and character variables. Make sure that no function returns a character string longer than 512 characters.

-4503

Description of Error: A function has not returned the correct number of values expected by the calling function. Corrective Action: Make sure that the number of parameters after the RETURN keyword in the called function is the same as the number of parameters after the RETURNING keyword in the calling statement.

-4504

Description of Error: A validation error has occurred as a result of the VALIDATE command. Corrective Action: Make sure that the values of the variables in a VALIDATE statement conform to the values allowed for the corresponding columns in the syscolval table.

-4508

Description of Error: PRINT FILE errorcannot open le lename for reading. Corrective Action: Check that the specied le exists, and that you have READ access to it. Contact your System Administrator if you need help with this action.

-4513

Description of Error: A number used as a DISPLAY AT location or SCROLL count must be positive. Corrective Action: Make sure that you use only positive integer expressions in DISPLAY AT or SCROLL statements.

-4517

Description of Error: Strings of length > 512 cannot be returned from function calls. Corrective Action: Make sure that a character string returned by a function does not exceed 512 characters.

-4518

Description of Error: The 4GL program cannot allocate any more space for temporary string storage. Corrective Action: INFORMIX-4GL cannot allocate more than 512 characters for temporary string storage. This error can occur if the nested functions in a CALL statement return strings whose total length exceeds 512 characters.

Error Messages 111

-4524

Description of Error: The program cannot be executed. Corrective Action: You may have tried to run a program that was not created by the p-code compiler. Recompile the program. If the problem recurs, call your Informix Representative.

-4527

Description of Error: Undened opcode in function function-name. Corrective Action: The p-code le has been corrupted. Recompile the program.

-4529

Description of Error: A select statement could not be prepared for selecting rows from a temporary table used for a report. Corrective Action: Recompile the program. If the problem recurs, call your Informix Representative.

-4530

Description of Error: Cannot close and free a cursor used to process a report. Corrective Action: Recompile the program. If the problem reoccurs, call your Informix Representative.

-4531

Description of Error: The le lename starts with a bad magic number. You may have tried to run a le that was not created by the 4GL p-code compiler. Corrective Action: The p-code le has been corrupted. Recompile the program.

-4534

Description of Error: Wordwrap may not be used within report headers or trailers. Corrective Action: In the FORMAT section of a report, you cannot use the WORDWRAP keyword in the PAGE HEADER, PAGE TRAILER, or FIRST PAGE HEADER control blocks.

-4600

Description of Error: No form by specied name found. Corrective Action: Check the spelling of the form name. Check that the form exists in the current directory or in one of the directories specied by DBPATH.

-4601

Description of Error: No 4GL module by specied name found. Corrective Action: Check the spelling of the module name. Check that the module exists in the current directory or in one of the directories specied by DBPATH.

112

Error Messages

-4602

Description of Error: No 4GL program by specied name found. Corrective Action: Check the spelling of the program name. Check that the program exists in the 4GL program database.

-4603

Description of Error: No executable 4GL program by specied name found. Corrective Action: Check the spelling of the program name. Check that the program exists in the INFORMIX-4GL program database. Check the setting of the DBPATH variable.

-4604

Description of Error: Error(s) found in 4GL module. Corrective Action: Select the Correct option and correct the errors indicated by the error messages.

-4607

Description of Error: The following errors were discovered during compilation. Corrective Action: Examine the .err les to determine the problem. Modify the appropriate INFORMIX-4GL les and recompile. You can use the vi editor to edit le.err to look at the error le and use the Module-Modify option to change the le and recompile.

-4608

Description of Error: The compilation of the program was not successful. Corrective Action: Check that you have used the correct syntax for the statements in your program. You may have used a reserved word as an identier.

-4609

Description of Error: Insufcient memory is available to complete program compilation. Corrective Action: Divide your program into smaller modules. Recompile the program.

-4610

Description of Error: Warning(s) found in 4GL module. Corrective Action: When you compiled with the -ansi option, Informix extensions to ANSI standard syntax were found in your source code. If you want your source code to conform with ANSI SQL standards, you must edit and recompile your source code to include only ANSI statements. See Chapter 7 of this manual for a list of the Informix extensions to the ANSI standard syntax for SQL.

-4611

Description of Error: There is no 4GL source available for this program. Corrective Action: Check the program denition le for the names of the modules that make up the program.

Error Messages 113

-4612

Description of Error: Data validation table does not currently exist for this database. Corrective Action: If the syscolval table exists, make sure that it resides in the current directory or in a directory specied by DBPATH. Otherwise, select the Yes option to create it.

-4613

Description of Error: Screen display attribute table does not currently exist for this database. Corrective Action: If the syscolatt table exists, make sure that it resides in the current directory or in a directory specied by DBPATH. Otherwise, select the Yes option to create it.

-4614

Description of Error: A program already exists by this name. Corrective Action: Make sure that the name of each program is unique.

-4615

Description of Error: Invalid program name. Corrective Action: A program name cannot exceed ten characters. Make sure that the program name begins with a letter. The rest of the name can contain any combination of letters, numbers, and underscores (_).

-4616

Description of Error: The 4GL program database does not exist. Please create via PROGRAM section. Corrective Action: If the syspgm4gl program database does not exist, create it by using the Program option of the Programmers Environment. If syspgm4gl does exist, make sure that it resides in the current directory or in a directory specied by the DBPATH environment variable.

-4617

Description of Error: You may not edit a program located on a different device. Corrective Action: You cannot specify a pathname to a source le in a directory that is not on the device that holds your current directory. Use a system utility to copy the source le to your current directory (or to a directory on the current device).

-4618

Description of Error: An error has occurred in accessing the requested le. Corrective Action: Something prevented your access to the le. This could be a hardware problem, your le system could be out of disk space, or you may not have permission to access the le or the directory. Contact your System Administrator.

114

Error Messages

-4620

Description of Error: ESQL/C from Informix Software is not installed on the system. Corrective Action: You must purchase and install INFORMIX-ESQL/C if you want your INFORMIX-4GL application program to contain the .ec les. Otherwise, you must remove all mention of the .ec les in the program denition.

-4621

Description of Error: An error occurred while writing to output le lename. Corrective Action: Something prevented your access to the le. This could be a hardware problem, your le system could be out of disk space, or you may not have permission to access the le or the directory. Contact your System Administrator.

-4622

Description of Error: No runable 4GL program by specied name found. System Action: INFORMIX-4GL prompts you to enter the name of an existing executable program. Corrective Action: Check the spelling of the program name. Check that the executable program exists in the current directory or in one of the directories specied by DBPATH.

-4623

Description of Error: memory allocation error Corrective Action: The process was unable to acquire the amount of memory which it requested. Divide your program into smaller modules, or reduce the complexity of the program.

-4624

Description of Error: Owner name user has exceeded 8 characters in length. Corrective Action: The name of an owner can have up to eight (8) characters. Check to make sure that the correct name was supplied.

-4625

Description of Error: FIXTIME FAILED Corrective Action: This is an internal error. After verifying that the error has not been generated as the result of a system limit or problem, please notify the Informix Technical Support Department.

-4626

Description of Error: Could not open le lename. Corrective Action: Check the directory listing for this le. It might not exist, or permissions might be set that prevent the program from reading the le.

-4627

Description of Error: The program cannot exit an INPUT statement at this point because it is not within an INPUT statement. Corrective Action: See if you inadvertently added or deleted statements when you edited your source le.
Error Messages 115

-4628

Description of Error: The program cannot exit a DISPLAY ARRAY statement at this point because it is not within a DISPLAY ARRAY statement. Corrective Action: See if you inadvertently added or deleted statements when you edited your source le.

-4629

Description of Error: Load from le lename failed. Corrective Action: A conversion error occurred, or there was insufcient space to complete the load. Check your disk space availability and the le size.

-4630

Description of Error: Unload to le lename failed. Corrective Action: A conversion error occurred or there was insufcient space to complete the load. Check your disk space availability and the le size.

-4631

Description of Error: Starteld of DATETIME or INTERVAL qualiers must come earlier in the time-list than its endeld. Corrective Action: You may have reversed the order of qualiers, or substituted one keyword for another in specifying the qualiers. Specify the largest unit rst, and the smallest last.

-4632

Description of Error: Parenthetical precision of FRACTION must be between 1 and 5. No precision can be specied for other time units. Corrective Action: You either specied an out-of-range precision for the FRACTION eld, or else you attempted to specify non-default precision for a DATETIME eld other than FRACTION. See Appendix J for the distinction between INTERVAL and DATETIME data types.

-4633

Description of Error: DATETIME units can only be YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and FRACTION. Corrective Action: Substitute a valid qualier from among the keywords listed in the error message for whatever keyword you invented or misspelled. Do not append S to a keyword.

-4634

Description of Error: Symbol name must be a SQL database item name either a database name, a table name or a column name. Corrective Action: Check your spelling of the identier of the SQL object. You may be in the wrong database.

116

Error Messages

-4635

Description of Error: Cannot create temporary le lename to contain a blob variable. Corrective Action: An I/O error occurred while trying to write the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.

-4638

Description of Error: The maximum size for varchar must be between 1 and 255. Corrective Action: You can use the CHAR data type to store strings larger than 255 bytes.

-4639

Description of Error: Real column name cannot be specied here. The symbol "*" is expected instead. Corrective Action: Substitute the asterisk ( * ) notation for a column name or list of names.

-4640

Description of Error: Table name is expected here. Corrective Action: Specify the name of a table in the current database.

-4641

Description of Error: Column name is expected here. Corrective Action: Specify the name of a column in the current database. You must prex it with the table identier, if other columns in the same database have the same name.

-4642

Description of Error: Subscripting is NOT allowed here. Corrective Action: Modify your code so that no subscript appears in this statement, and recompile.

-4643

Description of Error: A eld in the INTERVAL qualier is out of range. The acceptable ranges are from YEAR to MONTH and from DAY to FRACTION. Corrective Action: You cannot include both MONTH and smaller elds, or DAY and larger elds, in the precision of an INTERVAL value.

-4644

Description of Error: The HELP and ATTRIBUTE clauses each can be specied only once. Corrective Action: Delete all but one clause of each type from the statement, and recompile.

-4645

Description of Error: 4GL does not support returning a blob variable. Corrective Action: Rewrite the function so that no BYTE nor TEXT value appears in the RETURNING clause, and recompile.
Error Messages 117

-4646

Description of Error: The specied WORDWRAP RIGHT MARGIN value is out of range. It must be greater than or equal to the current column and less than or equal to the reports right margin. Corrective Action: Modify your report routine so that the RIGHT MARGIN specication is a column between the current column and the report margin, and recompile.

-4647

Description of Error: Cannot open le lename to read a TEXT variable value. Corrective Action: An I/O error occurred while trying to read the temporary le in which the TEXT or BYTE variable is stored. This can be caused by insufcient space on the disk, or by le corruption.

-4648

Description of Error: I/O error while running fglc. Corrective Action: Check space availability on your disk. When enough space has been made available, rerun fglc.

-9143

Description of Error: Character, Text, and Byte data cannot be printed with "using" formats. Corrective Action: Be sure you have not attempted to use the USING keyword with Character, Text, and Byte data. You can only use it with date and number data.

1203

Description of Error: Cannot nd message le. Check INFORMIXDIR and

DBLANG.

Corrective Action: INFORMIX-4GL cannot locate a needed message le. Check that both the INFORMIXDIR and DBLANG environment variables are set with the appropriate pathname. Contact your System Administrator if you need help with this action. 1204 Description of Error: Type of terminal is unknown to the system. Corrective Action: Check the setting of the TERM environment variable. Check to see that your TERMCAP or TERMINFO environment variables have been set to the correct les. TERMCAP is usually set to /etc/termcap or $INFORMIXDIR/etc/termcap, TERMINFO is usually set to /usr/lib/terminfo or $INFORMIXDIR/lib/terminfo. Contact your System Administrator if you need help with this action. 1310 Description of Error: Program error at module-name, line number line-number. Corrective Action: A statement in the indicated line cannot be executed (possibly because of an error or omission earlier in your program).

118

Error Messages

1354

Description of Error: <byte value> Corrective Action: This contains a binary large object (BLOB) of type BYTE.

2002

Description of Error: You have entered the wrong number of parameters. The call format is as follows: form4gl -d form-name database-name table1 table2 ... Corrective Action: Check the sequence of parameters present on the command line.

2005

Description of Error: Database database-name not found or not correct format. Corrective Action: Check that the DBPATH environment variable includes the full pathname of the directory holding the database. Contact your System Administrator if you need help with this action.

2008

Description of Error: The table table-name does not exist in the database. Corrective Action: The table name included in the TABLE section of the form specication le is not found in the database specied in the DATABASE section. Check the spelling of the table name.

2009

Description of Error: You have not selected any database tables. Corrective Action: You must include one or more table names in the TABLES section of the form specication le.

2010

Description of Error: There is not enough memory to use the default form option for this particular choice of tables. Corrective Action: You have exceeded the data space limits of your machine. Reduce the number of tables included in the form.

2011

Description of Error: Default FORM4GL has run out of memory. Corrective Action: You have exceeded the data space limits of your machine. Reduce the number of tables included in the form. Recompile the form specication.

2012

Description of Error: Form output table form-name could not be opened. Corrective Action: You may have exceeded the open le limit of 14 data les (this number includes the output le). Reduce the number of tables included in the form. Recompile the form specication.

Error Messages 119

2017

Description of Error: The default form has exceeded its label limit. Corrective Action: A form can use up to 26 one-character elds, 260 twocharacter elds, and 1000 elds of three characters or more. Reduce the number of tables in the default form. Recompile the form specication.

2018

Description of Error: The default form has exceeded its limit of 260 twocharacter labels. Corrective Action: The total number of two-character elds contained in the tables used to generate the default form exceeds the 260 limit. You must delete one or more of the tables containing two-character elds. Recompile the form specication.

2019

Description of Error: The default form has exceeded its limit of 26 one-character labels. Corrective Action: The total number of one-character elds contained in the tables used to generate the default form exceeds the 26 limit. You must delete one or more of the tables containing one-character elds. Recompile the form specication.

2020

Description of Error: The following tables are involved: table-name. Corrective Action: The indicated tables are involved in the specied error(s).

2028

Description of Error: The form compilation found warnings and no errors. Corrective Action: You can use the form, but check the specied le to check the warnings.

4150

Description of Error: Program error at module-name, line number line-number. Corrective Action: A statement in the indicated line cannot be executed (possibly because of an error or omission earlier in your program).

4152

Description of Error: FORMS statement error number error-number. Corrective Action: Something is wrong with the input, display, or data type conversion that your program species. Refer to the corresponding error number in this manual. (This error can occur with statements that do not use screen forms.)

4153

Description of Error: SQL statement error number error-number. Corrective Action: Refer to the corresponding error number in this manual.

120

Error Messages

4154

Description of Error: Program stopped at module-name, line number line-number. Corrective Action: Look for additional messages to see why execution stopped.

4155

Description of Error: 4GL run-time error number error-number. Corrective Action: Refer to the corresponding error number in this manual.

4156

Description of Error: ISAM error number error-number. Corrective Action: Refer to the corresponding error number in this manual.

Error Messages

121

122

Error Messages

B C

Index

Index

A
a command-line option 1-62 A symbol in PICTURE format strings 4-38 ABSOLUTE keyword, FETCH statement 3-17, 7-98 Accept key 7-166 ACCEPT KEY keywords, OPTIONS statement 7-79, 7-166 Access privileges 3-41 ALL 7-115, 7-187 ALTER 7-16, 7-115, 7-187 CONNECT 3-41, 7-52, 7-116, 7-187, E-23 database privileges 7-42, 7-116 DBA 3-41, 7-116, 7-187 default 3-41 DELETE 7-115, 7-187 for a synonym 7-47 for database administrator 3-41 FROM PUBLIC 7-188 INDEX 7-115, 7-187 INSERT 7-115, 7-187, E-14 removing 7-187 RESOURCE 3-41, 7-116, 7-187 SELECT 7-115, 7-187, 7-204 table privileges 3-41, 7-115 TO PUBLIC 3-41, 7-116 UNIX permissions 7-42 UPDATE 7-115, 7-187 view privileges 3-60, 7-117 ACTION Menu (upscol utility) E-38 Active set of a query 2-22, 3-14 ADD keyword, ALTER TABLE statement 7-14

AFTER DELETE clause INPUT ARRAY 7-133 AFTER FIELD clause INPUT ARRAY statement 7-132 AFTER GROUP OF control block 2-48, 5-25 AFTER keyword INPUT ARRAY statement 7-130 INPUT statement 7-123 REPORT statement 5-25 Aggregate function AVG 5-46, 7-249 COUNT 5-46, 7-249 GROUP 5-46, 7-223 in a query 5-46, 7-223, 7-240, 7-249 in a report 2-47, 5-26, 5-44 MAX 5-46, 7-249 MIN 5-46, 7-249 PERCENT 5-46 SUM 5-46, 7-249 with ALL 7-249 with DISTINCT or UNIQUE 7-250 with NULL values 3-55, 5-46, 7-250 Alias of a table in a form specification file 4-14, 4-60, 7-35 in a SELECT statement 7-226, 7-235 ALL keyword aggregate functions 7-249 dbschema utility E-22 GRANT statement 7-115 REVOKE statement 7-187 SELECT statement 7-222, 7-237 with UNION operator 7-246

ALTER INDEX statement 3-12, 7-12 ALTER keyword GRANT statement 7-115 REVOKE statement 7-187 ALTER TABLE statement 7-14 Ampersand (&) symbol 2-44 AND keyword Boolean operator 2-13, 3-55 COLOR attribute 4-25 WHERE clause 7-234 with BETWEEN 4-25, 7-230 Angle ( < ) brackets 4-42 ansi option of c4gl command 1-33, 7-7 option of fglpc command 1-62, 7-7 warning message 3-6, 7-7, 7-65 ANSI standards for SQL compatibility with 7-7 ANY keyword, SELECT statement 7-237 Application program, compiling 1-27, 1-32, 1-56, 1-61, 7-7 Arguments for 4GL program command line 6-5, 6-17 for a 4GL function 7-19, 7-110 for a 4GL report 5-6 passed to a C function 2-55, 7-19, F-1 arg_val function 6-4 Arithmetic operators in a SELECT clause 7-219, J-9 in expressions 2-11, 2-36, 4-25 Array displaying 7-79, 7-192 of records 4-55, 6-7 program array 2-10, 6-6, 7-71, 7-79 screen array 4-55, 7-79, 7-192 ARRAY data type 2-10, 5-8, 7-79 ARRAY keyword DEFINE statement 7-71 DISPLAY ARRAY statement 7-79 INPUT ARRAY statement 7-129 Arrow keys I-4

arr_count function 6-6 examples 7-135 arr_curr function 6-7 examples 7-135 AS keyword CREATE VIEW statement 7-57 GRANT statement 7-116, E-23 ASC keyword CREATE INDEX statement 7-44 ORDER BY clause 3-56, 7-243 ASCII characters collating sequence 4-35, H-2 from integer codes 2-25, H-2 ASCII files colornames I-18 form specifications 4-3 input data 7-143, E-11 output from UNLOAD 7-144, 7-203 .4gl source files 1-27, 1-56 ASCII function 2-25 Assignment statements 7-5 attributes of display fields 4-16 INITIALIZE 2-17, 7-120 LET 2-17, 7-142 Asterisk (*) notation arithmetic operator 2-11, 7-219 for all columns 2-15, 7-36 for all fields 4-54, 7-36 for record elements 2-15, 4-55, 7-111 in a REPORT routine 5-6 in a SELECT clause 7-222 in a USING format string 2-44 screen field overflow 2-46, 4-11, 7-76 searching for * 7-33, 7-233 wildcard 7-34, 7-232 with the COUNT keyword 3-55, 5-46, 7-249 with the PERCENT keyword 5-46 AT keyword DISPLAY statement 7-75 OPEN WINDOW statement 7-160 At ( @ ) sign 2-14, 3-7, 7-223

ATTRIBUTE keyword CONSTRUCT statement 7-32 DISPLAY ARRAY statement 4-59, 7-79 DISPLAY FORM statement 7-83 DISPLAY statement 4-59, 7-75 ERROR statement 7-92 INPUT ARRAY statement 7-135 INPUT statement 7-123, 7-129 MESSAGE statement 7-154 OPEN WINDOW statement 7-160 OPTIONS statement 7-168 PROMPT statement 7-173 Attribute types AUTONEXT 4-23, 4-57 BLINK 4-26, 4-59, 7-77, I-9, I-27 BOLD 4-59, 7-163, I-27 BORDER 7-163, I-6, I-24 COLOR 4-25, 4-63, E-40 COMMENTS 4-27, 4-57 DEFAULT 4-19, 4-29, 4-57, 7-121, E-39 DIM 4-59, 7-77, 7-163, I-27 DISPLAY LIKE 4-15, 4-31 DOWNSHIFT 4-32, E-39 FORMAT 4-33, E-41 INCLUDE 4-19, 4-35, 4-57, 7-212, E-39 INVISIBLE 4-59, 7-77, 7-163, I-27 LEFT 4-26, E-41 NOENTRY 4-37 NORMAL 4-59, 7-154, 7-163 PICTURE 4-38, 4-57 REQUIRED 4-40 REVERSE 4-26, 4-42, 4-59, 7-163, I-4, I-9, I-27 SHIFT 4-57, E-39 UNDERLINE 4-26, 4-59, I-9, I-27 UPSHIFT 4-43, E-39 VALIDATE LIKE 4-15, 4-45 VERIFY 4-46, 4-57 WORDWRAP 4-21, 4-47 ATTRIBUTES section of form specification assigning attributes 4-16 assigning field names 4-16 default values 4-56, 7-168, E-39 definition of 4-16

Index

field tags 4-17, 4-25 fields linked to columns 4-15, 4-17 for a multiple table form 4-6 for multiple-column fields 4-21 for multiple-line fields 4-20 format 4-16, 4-22 form-only fields 4-16, 4-18 input and display 4-22, 7-167 table of attributes 4-22, 4-26 AUDIT keyword CREATE AUDIT statement 3-46, 7-39 DROP AUDIT statement 3-46, 7-85 Audit trails 3-45 compared to transactions 3-45 CREATE AUDIT 3-45, 7-39 DROP AUDIT 3-45, 7-85 RECOVER TABLE 3-46, 7-179 AUTOINDEX PATH access method 7-194 Auto-indexing 3-52 AUTONEXT attribute 4-23, 4-57, E-39 AVG aggregate function 5-46, 7-249

B
Backup copy of a database 3-45, 3-46 bcheck utility E-2 BEFORE FIELD clause INPUT ARRAY statement 7-132 BEFORE GROUP OF control block definition of 5-27 guidelines for using 5-27 BEFORE keyword ALTER TABLE statement 7-14 INPUT ARRAY statement 7-130 INPUT statement 7-123 REPORT statement 5-27 BEGIN WORK statement explicit transactions 3-44 syntax and notes 7-18 Bell of a terminal, ringing 2-19, 2-25, 4-38, 7-92

BETWEEN keyword 3-65, 4-25, 4-58, 7-229 Binding to database and forms 2-14, 4-17 BLACK attribute 4-26, 4-59, 7-77, I-19 Blank characters DAY and HOUR separator 2-6, J-5, J-8 default character value 4-7, 4-29 in input files 7-144, E-12 in WORDWRAP fields 4-48 with CLIPPED operator 2-27 with FORMAT attribute 4-33 with SPACE or SPACES 5-50 BLINK attribute 4-26, 4-59, I-9, I-27 BLOB data Intro-7 BLUE attribute 4-26, 4-59, 7-77, I-19 BOLD attribute 4-59, 7-77, I-27 Boolean capabilities I-3, I-21 Boolean expression 2-13 examples 4-58, 7-230 in syscolatt 4-58, E-41 with CASE 7-22 with COLOR attribute 4-25, 4-63 with CONSTRUCT 7-33 with IF 7-118 with NULL values 3-55, 4-25 with WHERE 7-218, 7-228 with WHILE 7-216 Bordered window graphics characters used 4-13, 7-163, I-24 how displayed on screen 7-163 position on screen 7-160 BOTTOM MARGIN statement 5-16, 5-36 Bourne shell C-2 Braces ( { } ) symbols comment indicator 2-3, E-15 page layout of form specification 4-9 syntax convention Intro-10 Brackets ( [ ] ) symbols page layout of form specification 4-9 pattern matching 7-233 syntax convention Intro-9

to specify array elements 2-10 to specify substrings 2-12, 4-18 Built-in functions 2-24, 5-44 BY keyword CONSTRUCT statement 7-32 FORM4GL form specification file 4-8 GROUP BY clause 7-240 INPUT statement 2-14 ORDER BY clause 3-18, 7-243 REPORT statement 5-18, 7-184 SCROLL statement 7-192 BY NAME keywords CONSTRUCT statement 7-32 DISPLAY statement 7-75 INPUT statement 2-14, 7-122 BYTE data type Intro-7 B+ trees E-3

C
C Compiler version of 4GL Intro-3, 1-5, 1-7 C compiler, function 1-32 C functions 1-66, 2-55, 7-19 C language functions in 4GL programs 1-32, 1-64, 2-55 C shell C-2 c4gl command 1-6, 1-32, 7-7 CALL keyword, WHENEVER statement 7-213 CALL statement 2-18 passing parameters with 7-111 RETURNING clause 2-56, 7-19 syntax and notes 7-19 with C functions 1-70, 2-58, 7-19 with library functions 6-3 Calling convention for C functions 2-55 CASE statement 2-19 EXIT CASE 7-96 syntax and notes 7-21 cat utility 1-64, 3-45 cfglgo command 1-66, 1-69 CHAR data type acceptable values 3-8, 7-50 CHARACTER synonym 2-8, 3-8 subscripts 4-18, 4-19, 7-220

Index 3

with database columns 3-8, 7-50 with display fields 4-38, 4-47 with variables 2-8, 7-71 CHAR keyword, PROMPT statement 7-173 CHARACTER data type 2-8, 3-8 Character position 2-8, 4-18, E-13 C-ISAM (indexed sequential access method) Intro-4, 3-50 CLEAR statement 2-19 syntax and notes 7-23 WINDOW 7-60 CLIPPED keyword 2-12 in a string expression 2-38, 5-40 syntax and notes 2-27 with DISPLAY 7-76 CLOSE DATABASE statement definition of 3-11 syntax and notes 7-27 CLOSE FORM statement closing an opened form 2-20, 7-159 syntax and notes 7-28 CLOSE statement and the FREE statement 7-109 and the SQLCA record 3-28 syntax and notes 7-25 with a SELECT cursor 3-17, 7-25 with an INSERT cursor 3-26, 7-25 CLOSE WINDOW statement 2-20 syntax and notes 7-30 CLUSTER keyword ALTER INDEX statement 3-53, 7-12 CREATE INDEX statement 3-53, 7-44 Colon ( : ) symbol as statement label prefix 7-213 delimiter in DATETIME values 2-6, 7-34, E-12, J-5, J-8 delimiter in INTERVAL values 2-6, 7-34, E-12 field specification separator E-14, I-4 LABEL statement 7-141 ranges with CONSTRUCT 7-34 WHENEVER statement 7-213 COLOR attribute 4-25, 4-63, I-19 colornames file 4-59, E-40, I-9, I-18

Column adding 7-14 changing column values 3-17, 7-206 changing data type 7-14 constraints 7-16, 7-53 designated as NOT NULL 7-51 determining length 7-52 indexed 3-50, 7-44 joining 7-234, G-1 naming conventions 3-6, 7-51 NULL value in 3-54 removing 7-14 renaming 7-181 virtual 3-59, 7-58 Column data types CHAR 2-8, 7-50 DATE 2-9, 7-51, C-3 DATETIME 2-9, 7-52, J-1 DECIMAL 2-7, 7-50, F-1 FLOAT 2-8, 7-50 INTEGER 2-7, 7-50 INTERVAL 2-9, 7-52, J-1 MONEY 2-8, 7-50, C-5 SERIAL 7-51, 7-139 SMALLFLOAT 2-8, 7-50 SMALLINT 2-7, 7-50 COLUMN keyword 2-29, 7-181 Columns in stores database tables A-2 in system catalogs B-1 in upscol tables 4-56, E-37 COLUMNS keyword, OPEN WINDOW statement 7-160 Comma ( , ) symbol concatenation operator 2-12, 7-172 in USING format strings 2-44 separator in lists 2-15, I-21 COMMAND clause MENU statement 7-149 Command file dbexport E-7 dbload E-12 dbschema E-22 Command line arguments of a 4GL program 6-5, 6-17 to compile a message file E-28

to compile a screen form 4-9, 4-62 to create a customized runner 1-69, 1-71 to invoke a 4GL program 1-6, 1-31, 1-64, 1-65, 1-72, 6-5, 6-17 to invoke compiler 1-6, 1-32, 1-61 Comment indicators 2-3, 4-10, I-3, I-21 Comment line 7-162, E-39 COMMENT LINE keywords OPEN WINDOW statement 7-161 OPTIONS statement 7-165 COMMENTS attribute 4-27, 4-57, 7-35, E-39 COMMIT WORK statement 3-42 ending transactions 3-23, 3-44 syntax and notes 7-31 COMPILE Menu 1-27, 1-56 Compile option FORM Menu 1-17, 1-47, 4-61 MODULE Menu 1-12, 1-41 PROGRAM Menu 1-22, 1-51 Compile-time errors 1-11, 1-40, 4-61, 7-7 Compiling command line 1-31, 1-32, 1-61 help messages E-27 in Programmers Environment 1-10, 1-31, 1-39, 1-61 programs that call C functions 1-65 screen forms 1-15, 1-45, 4-60 with ansi flag 1-32, 1-62, 3-6, 7-7 Composite column list 7-16, 7-53 COMPRESS keyword, WORDWRAP attribute 4-48 Concatenation operator 2-12, 7-172 Concurrency control 3-42, 7-99 Conditional statements CASE 2-19, 7-21 COLOR attribute 4-25, 4-63 IF 2-19, 3-22, 7-118 syscolatt file 4-58, E-41 WHILE 7-216 CONNECT access privilege 3-41, 7-116, E-22

Index

CONNECT keyword GRANT statement 7-116 REVOKE statement 7-187 Constant date-time 2-12, J-1 floating number 2-5 integer 2-5 string 2-5 CONSTRAINT keyword ALTER TABLE statement 7-14 CREATE TABLE statement 7-49 Constraints 7-139 changing 3-11, 7-16 creating 3-11, 7-53 names 3-7, 7-16, 7-53 owner 3-7, 7-16 CONSTRUCT statement 2-20 NOENTRY fields 4-37 symbols recognized 7-33 syntax and notes 7-32 wildcard characters 7-34 CONTINUE keyword, WHENEVER statement 2-21, 2-22, 7-213 CONTINUE statement 2-19 FOR 7-105 FOREACH 7-107 MENU 7-152 syntax and notes 7-38 WHILE 7-216 Control blocks 5-23 COUNT aggregate function 3-55, 5-46, 7-249 CPU cost for a query 3-63, 7-194 CREATE AUDIT statement 3-45, 7-39 CREATE DATABASE statement 3-11 current database 7-41 syntax and notes 7-41 system catalogs 7-41 WITH LOG IN 3-43, 7-42 CREATE INDEX statement 3-12 syntax and notes 7-44 with ASC 7-16, 7-44, 7-53 with DESC 7-44 with UNIQUE and DISTINCT 7-44

CREATE SYNONYM statement 3-11, 7-47 CREATE TABLE statement 3-11 assigning data types J-3 guidelines for using 7-49 NOT NULL clause 3-54, 7-51 notes 7-51 owner naming 7-51 syntax 7-49 TEMP keyword 3-58, 7-51 UNIQUE keyword 7-53 WITH NO LOG 7-50 CREATE VIEW statement 3-58 guidelines for using 7-57 owner naming 7-57 syntax and notes 7-57 WITH CHECK OPTION 3-60, 7-58 Currency symbol default ( = $ ) 2-8, 4-29, C-5 in dbload input files E-12 in format strings 2-47 Current database 3-11 CLOSE DATABASE statement 7-27 closing 3-11, 7-27 creating 3-11, 7-41 DATABASE statement 7-62 FETCH statement 7-99 selecting 3-11, 7-62 CURRENT function 3-65, 7-258 CURRENT keyword CURRENT function 2-30, 3-65 DEFAULT attribute 4-30 DELETE statement 3-18, 7-73 FETCH statement 7-98 for a DATETIME value J-13 UPDATE statement 3-19, 7-207 CURRENT OF keywords DELETE statement 3-18, 7-73 UPDATE statement 3-19, 7-207 Current option of a menu 1-8, 1-37 Current row of a query 3-14, 3-18 Current window 7-23, 7-60, 7-161 CURRENT WINDOW statement 2-20 syntax and notes 7-60

Cursor 3-13 advancing 3-17, 7-98 closing 3-18, 7-25 declaring 3-14, 7-64 FOR UPDATE 3-17, 7-99, 7-157 non-SCROLLing 3-14 opening 3-17, 7-156 position 3-19, 3-20 scope of reference 2-5, 3-15, 7-67 SCROLL 3-14, 7-65 with CLOSE 3-16, 7-25 with DELETE 3-18 with FETCH 3-16, 7-99 with FOREACH 3-16 with FREE 3-40, 7-109 WITH HOLD 3-14, 3-25, 7-26, 7-65, 7-157 with INSERT 3-25, 7-9, 7-26, 7-65 with OPEN 3-16, 7-156 with SELECT 3-13, 7-64, 7-220 with UPDATE 3-17, 7-99, 7-207 CURSOR keyword DECLARE statement 3-14 Cursor movement I-22 as determined by FETCH 3-17 as determined by INPUT 7-125 in a menu 7-150 in a screen array 7-80 in a screen form 4-23, 7-35 in a screen record 4-16 Cursor WITH HOLD BEGIN WORK statement 3-25 COMMIT WORK statement 3-25 DECLARE statement 3-24, 7-65 FETCH statement 3-24 OPEN statement 7-157 customer table in stores database Intro-11, A-2 Customized runners 1-50, 1-66 CYAN attribute 4-26, 4-59, 7-77, I-19

D
Data access statements 7-6 GRANT 3-40 LOCK TABLE 3-40 REVOKE 3-40 UNLOCK TABLE 3-40

Index 5

Data conversion in an INSERT statement 7-140 in an UPDATE statement 7-208 in expressions 2-10, 2-36 Data definition statements 7-6 ALTER INDEX 3-12 ALTER TABLE 3-11 CLOSE DATABASE 3-11 CREATE DATABASE 3-11 CREATE INDEX 3-12 CREATE SYNONYM 3-11 CREATE TABLE 3-11 CREATE VIEW 3-11 DATABASE 3-11 DROP DATABASE 3-11 DROP INDEX 3-12 DROP SYNONYM 3-12 DROP TABLE 3-11 DROP VIEW 3-11 RENAME COLUMN 3-12 RENAME TABLE 3-11 UPDATE STATISTICS 3-12 Data fields E-12 Data integrity statements 3-42, 7-6 Data manipulation statements 7-6 DELETE 3-12, 7-73 INSERT 3-12, 7-138 LOAD 3-12, 7-143 SELECT 3-12, 7-193, 7-218 UNLOAD 3-12, 7-203 UPDATE 3-12, 7-206 Data type binary large objects (BLOB) Intro-7 C language 2-55, F-2 changing 7-14 conversion 2-10, 2-36, 7-140 date-time data types J-1 floating decimal point 2-8, 3-9 of columns in a table 3-8, 7-49 of variables 5-7, 7-71, 7-120 of view columns 7-58 storage requirements 7-52 synonyms 2-7 Data types ARRAY 2-10, 5-8 BYTE Intro-7 CHAR 2-8, 3-8, 4-29, 5-40, 7-50, E-14

CHARACTER 2-8, 3-8 DATE 2-9, 3-9, 4-29, 5-40, 7-51, C-3, E-12, J-10 DATETIME 2-9, 3-10, 4-30, 5-40, E-12, J-2 DEC 2-8, 3-9 DECIMAL 2-7, 2-10, 3-9, 4-33, 7-50, F-1 DOUBLE PRECISION 2-8, 3-9 FLOAT 2-8, 3-9, 4-33 INT 2-7, 3-8 INTEGER 2-7, 3-8, 7-50 INTERVAL 2-9, 3-10, 4-30, 5-40, E-12, J-5 LIKE specification 2-9, 5-7 MONEY 2-8, 3-9, 4-29, 5-40, 7-50, C-5, E-12 NUMERIC 2-8, 3-9 REAL 2-8, 3-9 RECORD 2-9, 5-7 SERIAL 2-9, 3-9, 4-37, 5-40, 7-51, 7-139 SMALLFLOAT 2-8, 3-9 SMALLINT 2-7, 3-8 TEXT Intro-7 VARCHAR Intro-7 Data validation upscol utility 4-56, E-39 using views 3-60 VALIDATE LIKE attribute 4-45 VALIDATE statement 2-24, 7-211 Database access privileges 3-41 closing 7-27 creating 3-64, 7-41 creating tables 3-11, 7-49 creating views 3-58, 7-57 data manipulation statements 3-12 database subdirectory 3-5, 7-41 granting user access 3-41, 7-115 indexes 3-50 map of stores A-5 naming conventions 3-6, 7-41 owner naming and MODE ANSI 3-7 recovering Intro-7, 3-45 relational 3-5 remote 7-35

removing 3-11, 7-86 removing indexes 3-12, 7-88 removing tables 3-11, 7-90 renaming tables 3-11, 7-182 replication with dbschema E-22 revoking user access 3-41, 7-187 stores demonstration A-1 system catalogs 3-5, B-1 tables in 3-5, 7-49 with a transaction log 3-42 Database administrator (DBA) access privileges 1-18, 3-41, 7-116 Database conversion with dbupdate utility E-25 with sqlconv utility E-31 Database engines Intro-6 DATABASE section of form specification creating as FORMONLY 4-7 definition of 4-7 format 4-6 WITHOUT NULL INPUT 4-7, 4-29 DATABASE statement 2-22 definition of 3-11, 7-62 EXCLUSIVE 7-63 syntax and notes 7-62 DATE data type acceptable values 2-46, 7-51 data conversion J-16 in dbload input files E-12 manipulating arithmetically J-10 with database columns 3-9 with display fields 2-46, 2-47, 4-29, 4-33, 7-52, C-3 with variables 2-9, 7-71 DATE keyword CREATE TABLE statement 7-51 DATE function 2-32 DATE() function 2-33, 7-9, 7-252 DATETIME data type 2-9, J-2 acceptable values 7-51, J-2 entered as a character string J-8 entered as a literal value 4-30, J-3 in dbload input files E-12 manipulating arithmetically 2-36, J-9

Index

using the CURRENT keyword J-13 with database columns 3-10 with display fields 4-30 with variables 2-9, 7-71, J-16 Date-time expression 2-12, 7-248 DAY keyword DATETIME qualifier 3-10, J-2 DAY( ) function 2-34, 7-9, 7-253 INTERVAL qualifier 3-10, J-12 DBA access privilege 3-7, 3-41, 7-16, 7-85, E-6, E-23 DBA keyword GRANT statement 7-116 REVOKE statement 7-187 DBA (Database Administrator) 3-40, 3-45 DBANSIWARN environment variable 3-6, 3-25, 3-64, 7-7, C-2 DBDATE environment variable C-3 DBDELIMITER environment variable 7-144, 7-203, C-3, E-12 DBEDIT environment variable 1-12, 1-26, 1-41, 1-55, C-4 dbexport utility E-6 DBLANG environment variable C-4, E-30 dbload utility E-11, E-33 DBMONEY environment variable C-5 DBPATH environment variable 1-18, 1-29, 1-58, C-6, E-23 DBPRINT environment variable 5-10, C-6 dbschema utility E-22 DBTEMP environment variable C-6 dbupdate utility 3-54, E-25 Deadlock 7-197 Debug option MODULE Menu 1-42 PROGRAM Menu 1-53 Debugger, Interactive Intro-4, 1-38, 1-53, 1-65 Debugger, invoking 1-59, 1-61 DEC data type 2-8, 3-9

DECIMAL data type acceptable values 2-7, 3-9, 7-50 DEC synonym 2-8, 3-9 floating decimal point in 2-7, 2-44, 3-9 NUMERIC synonym 2-8, 3-9 scale and precision 2-7, 2-10, 2-11 with database columns 3-9 with display fields 2-44, 4-33 with variables 2-7, 7-71, F-1 DECIMAL functions for C F-1 DECLARE statement and SQLCA record 3-63 assigning a cursor 3-14, 3-29 DELETE operations 3-25 FOR UPDATE 3-19, 7-66, 7-74 guidelines for using 3-35 INSERT cursor 3-26, 3-37, 7-139 SCROLL option 3-20, 7-65 SELECT cursor 3-14, 3-35 syntax and notes 7-64 WITH HOLD option 3-23, 7-65 DEFAULT attribute 4-29, 4-57 CURRENT 4-30 TODAY 4-30 with INITIALIZE statement 4-58, 7-121 with WITHOUT DEFAULTS 4-29, 7-124 with WITHOUT NULL INPUT 4-29 Default editor 1-26, 1-55, C-4 Default form specification file creating at system prompt 4-62 generating 1-16, 1-46, 4-61 modifying 1-16, 1-46, 4-61 Default screen attributes 4-56, 7-168 Default screen record 4-55 DEFER statement forms of 2-23 global flags set 2-23, 7-69 INTERRUPT 2-23 syntax and notes 7-69 DEFINE statement defining a program array 2-10 defining a record 2-9, 7-72 defining global variables 2-4, 7-112

defining variables 2-4, 2-7, 7-71 in a function 2-4, 7-110 in a report 2-4, 5-7, 7-184 LIKE keyword 2-9, 7-71 location 2-4 scope of variables 2-17 syntax and notes 7-71 Defining global variables 2-4, 7-112 Delete key 7-166, I-5, I-23 DELETE keyword GRANT statement 7-115 INPUT ARRAY statement 7-130 OPTIONS statement 7-166 REVOKE statement 7-187 DELETE statement 3-12 DATETIME or INTERVAL values J-15 examples 3-33 functions in 7-248 syntax and notes 7-73 WHERE CURRENT OF clause 3-18, 3-19 DELIMITER keyword dbload command file E-12 LOAD statement 7-143 UNLOAD statement 7-203 Delimiters in a screen form 4-11 changing 4-52 DELIMITERS statement 4-52 Demonstration application, listing A-15 Demonstration database A-1 description of Intro-11, A-1 restoring 1-6 DESC keyword CREATE INDEX statement 7-44 ORDER BY clause 3-56, 7-243 DIM attribute 4-59, 7-77, I-8 Direct memory access (DMA) Intro-4 DISPLAY ARRAY statement 2-20 arr_curr function 6-7 EXIT DISPLAY 7-96 set_count function 6-20 syntax and notes 7-79 DISPLAY ATTRIBUTE keywords 7-168

Index 7

Display field 4-10 default field widths 4-11 determining field widths 4-11 dividing long CHAR columns 4-18, 4-19 field names 4-11, 4-16, 4-22 field tag 4-10, 4-25, 4-63 format of 2-44, 4-10 form-only field 4-16, 4-18 guidelines for using 4-11 labels for 4-12 multiple-column 4-21, 4-34, 4-42 multiple-line fields 4-11, 4-47 screen arrays 4-11, 4-54, 7-79 specifying search criteria 7-32 verifying field widths 4-12 DISPLAY FORM statement 2-20 syntax and notes 7-83 DISPLAY LIKE attribute 4-15, 4-31 DISPLAY statement 2-20 AT 2-27 BY NAME 7-76 CLIPPED 2-27 EXIT DISPLAY 7-96 formatting 2-46 syntax and notes 7-75 TO 2-15 DISTINCT keyword aggregate functions 3-55, 7-249 ALTER TABLE statement 7-16 CREATE INDEX statement 7-44 CREATE TABLE statement 7-53 SELECT statement 7-222 Distributed query across databases Intro-7 Documentation Intro-3 DOUBLE PRECISION data type 2-8, 3-9 DOWN keyword SCROLL statement 7-192 syscolval table 4-57, E-39 DOWNSHIFT attribute 4-32, 7-35, E-39 downshift function 6-9 DROP AUDIT statement 3-45, 7-85 DROP DATABASE statement 3-11 syntax and notes 7-86 DROP INDEX statement 3-12 syntax and notes 7-88

DROP keyword, ALTER TABLE statement 7-14 Drop option, PROGRAM Menu 1-24 DROP SYNONYM statement 3-12, 7-89 DROP TABLE statement 3-11 syntax and notes 7-90 DROP VIEW statement 3-58 syntax and notes 7-91 Dynamic management statements 7-6 DECLARE 3-29 EXECUTE 3-28 FREE 3-29 PREPARE 3-28

E
EBCDIC conversion of ASCII strings 2-58 Editor blanks (in multiple-line fields) 4-48 Ellipsis ( . . . ) symbols 7-150 syntax convention Intro-11 ELSE keyword, IF statement 7-118 END keyword CASE statement 2-19, 7-21 DEFINE statement 7-71 DISPLAY ARRAY statement 7-79 FOR statement 7-104 FOREACH statement 7-106 FORM4GL form specification file 4-10 FUNCTION statement 7-110 GLOBALS statement 7-112 IF statement 7-118 INPUT ARRAY statement 7-130 MAIN program block 7-148 MENU statement 7-150 PROMPT statement 7-174 REPORT statement 5-20, 7-184 WHILE statement 3-27, 7-216 Environment variable DBANSIWARN 3-6, 3-64, 7-7, C-2 DBDATE C-3 DBDELIMITER 7-144, 7-203, C-3

DBEDIT 1-12, 1-15, 1-26, 1-41, 1-45, 1-55, 4-61, C-4 DBLANG C-4, E-30 DBMONEY C-5 DBPATH 1-18, 1-29, 1-58, 7-62, C-6 DBPRINT 5-10, C-6 DBTEMP C-6 INFORMIXDIR C-7, E-30 INFORMIXTERM C-7, I-1, I-20 SQLEXEC C-7 TERMINFO I-20, I-25 Equal ( = ) sign 2-13, 4-16, 7-33 Error handling 4GL library functions 6-10 built-in functions 2-22 compile-time errors 1-11, 1-40, 4-63 creating an error log 6-23 displaying error messages 6-11, 7-92 errorlog function 6-13 exception handling 2-23, 7-69 Interrupt key 2-21, 7-69 logging programmer-defined error messages 6-13 overview of 2-21 run-time errors 1-65, 2-21, 6-23 SQLCA global record 2-22, 3-63 startlog function 6-23 trapping errors 2-22, 7-214 trapping interrupts 2-23, 7-69 trapping warnings 2-22, 7-213 WHENEVER statement 2-22 with status variable 2-22, 6-10 ERROR keyword ERROR statement 7-92 OPTIONS statement 7-165 WHENEVER statement 7-213 Error line err_print function 6-11 err_quit function 6-12 location 7-167 Error log file 6-13, 6-23, E-11 Error messages 1-35, 6-10, 6-12, 6-23 editing the 4glusr.msg file E-29 Error record 6-23 ERROR statement 2-19, 7-92

Index

errorlog function 2-23, 6-13 err_get function 2-23, 6-10 err_print function 2-23, 6-11 err_quit function 2-23, 6-12 Escape key 7-167 ESCAPE keyword, WHERE clause 7-231, 7-232 ESQL/C functions 1-32, 1-64 language Intro-4 EVERY ROW keywords default FORMAT section of a report 5-20 ON EVERY ROW control block 5-31 EXCLUSIVE keyword DATABASE statement 7-62 LOCK TABLE statement 3-49, 7-146 Exclusive mode, opening the database 3-45, 7-200, E-6 EXECUTE statement 3-28 guidelines for using 3-33 syntax and notes 7-94 USING 3-33 EXISTS keyword, SELECT statement 7-238 Exit option FORM Menu 1-18, 1-47 MODULE Menu 1-14, 1-43 PROGRAM Menu 1-24, 1-53 EXIT statement 2-19 CASE 7-21 DISPLAY 7-79 FOR 7-105 FOREACH 7-107 INPUT ARRAY 7-130 MENU 3-23, 7-150 PROGRAM 7-97 syntax and notes 7-96 WHILE 7-216 Expression 2-11 Boolean 2-13, 3-55, 7-21 data conversion 2-10, J-11 date-time 2-12, 2-36, J-1, J-11 in a report 5-44 in a SELECT statement 7-219 NULL values 3-54

number 2-11, 2-44 string 2-12 using in statements 2-13 EXTEND function 2-35, 7-260, J-11 EXTERNAL keyword REPORT statement 5-18, 7-184

F
FALSE (Boolean constant) 2-5, 3-55 FETCH statement default condition 7-99 examples 3-36 guidelines for using 3-16 NOTFOUND code 3-63, 7-99 syntax and notes 7-98 with SELECT 3-36, 7-224 fgiusr.c file 1-67 fgldb command 1-66 fglgo command 1-6, 1-50, 1-64, 6-4 fglpc command 1-6, 1-61, 7-7 FIELD keyword INPUT ARRAY statement 7-130 INPUT statement 7-123 Field names in screen forms 4-15, 4-17, 6-14 Field tag 4-9 generated by FORM4GL 4-11 in Boolean expressions 4-25, 4-63 in the ATTRIBUTES section 4-16 in the SCREEN section 4-10, 4-11 naming conventions 4-17 Fields of input records 7-143, E-11 File extensions .4be 1-36, 1-73 .4bl 1-35, 1-73 .4bo 1-35, 1-73 .4ge 1-10, 1-13, 1-20, 1-35, A-15 .4gi 1-49, 1-54, 1-56, 1-58, 1-64, 1-72 .4gl 1-11, 1-26, 1-32, 1-35, 1-54, 1-55, 1-61, 1-72, A-15 .4go 1-50, 1-54, 1-56, 1-61, 1-62, 1-64, 1-72 .c 1-21, 1-35, 1-69 .dat 3-5, E-2 .dbs 3-5 .ec 1-21, 1-29, 1-32, 1-35, 1-69

.erc 1-35, 1-72 .err 1-31, 1-35, 1-60, 1-72, 4-12, 4-63, 7-7 .exp E-7 .fbm 1-36, 1-73 .frm 1-35, 1-72, 4-61, 4-62, 4-63 .h 1-70, F-1 .idx 3-5, E-2 .msg E-29 .o 1-10, 1-27, 1-35 .out 1-33, 1-69, 7-194, E-6 .pbr 1-36, 1-73 .per 1-15, 1-35, 1-72, 4-63 .sql E-7 .src A-15 FILE keyword dbload command file E-12 OPTIONS statement 7-166, E-27 Fill character ampersand 2-44 asterisks 2-44 dollar sign 2-45 parentheses 2-45 pound sign 2-44, 4-33 table of 2-44 Filters in a query 7-194, G-3 FINISH REPORT statement 2-21 guidelines for using 5-33 syntax and notes 7-101 FIRST keyword FETCH statement 3-23, 7-98 OPEN WINDOW statement 7-161 OPTIONS statement 7-167 REPORT statement 5-29 FIRST PAGE HEADER control block 5-29, 5-34 Fixed-length records E-12 FLOAT data type acceptable values 3-9, 7-50 DOUBLE PRECISION synonym 2-8, 3-9 with database columns 3-9 with display fields 4-33 with variables 2-8, 7-71 Floating number constant 2-5

Index 9

FLUSH statement guidelines for using 3-26 status variable and SQLCA record 3-28 syntax and notes 7-102 FOR keyword CONTINUE statement 7-38 CREATE AUDIT statement 3-46, 7-39 CREATE SYNONYM statement 7-47 DECLARE statement 3-25, 7-64 DROP AUDIT statement 7-85 PROMPT statement 7-173 UPDATE STATISTICS statement 7-210 FOR statement 2-18 EXIT FOR 7-96 syntax and notes 7-104 FOR UPDATE cursor DECLARE statement 3-17, 7-64 DELETE statement 3-18 FETCH statement 3-19, 7-99 FOREACH statement 3-19 OPEN statement 3-48, 7-157 row-level locking 3-48 FOREACH statement 2-18 CONTINUE FOREACH 7-38 examples 3-16 EXIT FOREACH 7-96 syntax and notes 7-106 Foreground colors 7-168, I-17 FORM Design Menu 1-14, 4-61 FORM keyword CLEAR statement 7-23 CLOSE FORM statement 7-28 OPEN FORM statement 7-159 OPEN WINDOW statement 7-160 OPTIONS statement 7-168 FORM LINE keywords OPEN WINDOW statement 7-161 OPTIONS statement 7-166 Form specification file, sections of ATTRIBUTES 4-4, 4-16, 7-167 DATABASE 4-4, 4-7 INSTRUCTIONS 4-51

SCREEN 4-4, 4-8 TABLES 4-4, 4-14 Form specification file, using 4-3 correcting errors 1-16 creating 4-62 default form specification file 4-62 generating 1-14, 1-43, 4-61 graphics characters 4-12 identifier 2-5, 7-28, 7-159 multiple tables in 4-14, 4-61 overview 4-3 PERFORM forms 4-63 structure 4-4 FORM4GL attribute syntax 4-22 command line syntax 4-9, 4-62, 4-63 creating a default form specification file 4-61 default display field 4-9 default field tags 4-62 default screen records 4-54 description 4-3 file extensions created by 4-63 from Programmers Environment 1-17, 1-46, 4-61 graphics characters in screen section 4-12 subscripting a CHAR column 4-18 using defaults in syscolval and syscolatt 4-17 verifying field widths 4-12 FORMAT attribute 4-33 guidelines for using 4-33 multiple-column fields 4-21 FORMAT section of REPORT statement AFTER GROUP OF 5-25 aggregate functions 5-46 BEFORE GROUP OF 5-27 CLIPPED 5-40 COLUMN 5-35 control blocks 5-23 definition of 5-20, 7-184 EVERY ROW 5-13, 5-21 fill characters 2-44 FIRST PAGE HEADER 5-29

LINENO 5-48 NEED statement 5-38 ON EVERY ROW 5-31 ON LAST ROW 5-33 PAGE HEADER 5-34 PAGE TRAILER 5-36 PAGENO 5-49 PAUSE statement 5-39 PRINT FILE statement 5-42 PRINT statement 5-40 SKIP statement 5-43 SPACE 5-50 TIME 2-41 USING 5-40 WORDWRAP 5-40, 5-51 Format strings with FORMAT attribute 4-33, E-41 with PICTURE attribute 4-38 with USING operator 2-44 Formatting a report automatic page numbering 5-35 default report format 5-21 formatting dates 2-46, C-3 formatting numbers 2-44 grouping data 5-46 page headers and trailers 5-29, 5-34, 5-36 printing column headings 5-35 setting margins 5-12, 5-13, 5-15, 5-16 setting page length 5-17 skipping to top of page 5-43 starting on a new page 5-38 Formatting number expressions 2-44 Form-only field 4-18, 4-19, 4-22 FORMONLY keyword ATTRIBUTES section 4-18 DATABASE section 4-7, 4-15 INSTRUCTIONS section 4-54 FRACTION keyword DATETIME qualifier 3-10, J-2 INTERVAL qualifier 3-10, J-6 FREE statement 3-29, 3-39, 7-109 FROM clause OUTER keyword 3-62, 7-226, G-3 SELECT statement 3-62, 7-226 table alias 7-235

10

Index

FROM keyword CONSTRUCT statement 7-32 DELETE statement 7-73 INPUT ARRAY statement 7-129 INPUT statement 7-122 LOAD statement 7-143 OPEN FORM statement 7-159 PREPARE statement 3-30, 7-171 PUT statement 7-177 REVOKE statement 7-187 SELECT statement 3-62 Function ASCII 2-25 CLIPPED 2-27 COLUMN 2-29 CURRENT 3-65, 4-30, 7-258, J-13 DATE 2-32 DATE() 2-33, 7-252 DAY() 2-34, 7-253 EXTEND() 2-35, 7-9, 7-260 LENGTH() 2-38, 7-9 MDY() 2-39, 7-254 MONTH() 2-40, 7-9, 7-255 SPACES 5-50 TIME 2-41 TODAY 2-42, 3-65, 4-30, 7-9 USER 3-65 WEEKDAY( ) 2-53, 7-9, 7-256 WORDWRAP 5-51 YEAR( ) 2-54, 7-9, 7-257 Function keys 1-50, I-5, I-23 FUNCTION statement and variables 2-17 defining a record in 7-111 parameters in 2-17, 7-110 RETURN 7-110, 7-186 syntax and notes 7-110 Functions 2-17 4GL library 2-22, 6-3 aggregate 3-55, 7-249 built-in functions 2-24 C language 1-32, 1-64, 2-55, F-1 calling a function 7-19, 7-111 in an expression 6-3 INFORMIX-ESQL/C 1-32, 1-64 values returned 2-17, 7-111

G
Generate option, FORM Menu 1-16, 1-46 Global flags 2-23 Global Source array 1-50 Global variables 2-4 GLOBALS statement 2-18 syntax and notes 7-112 with DEFINE LIKE 7-112 GO TO or GOTO keywords WHENEVER statement 7-213 GOTO statement LABEL 2-19, 7-114, 7-141 syntax and notes 7-114 GRANT statement 3-40, 7-10 CONNECT 3-41 DBA 3-41 RESOURCE 3-41 syntax and notes 7-115 table privileges 3-41 Graphics characters in forms 4-12 Greater ( > ) than symbol 1-64, 2-13, E-19 relational operator 2-13, 7-33 REVERSE attribute 4-42 GREEN attribute 4-26, 4-59, 7-77, I-19 GROUP aggregate functions 5-46 GROUP BY clause, SELECT statement in definition of a view 3-59 syntax and notes 7-240 with NULL values 3-56 GROUP keyword AFTER GROUP OF control block 5-25 BEFORE GROUP OF control block 5-27 REPORT statement 5-46

H
HAVING clause, SELECT statement 7-242 HEADER keyword FIRST PAGE HEADER control block 5-29 PAGE HEADER control block 5-34 Help file calling help messages 7-150, 7-151, 7-166, 7-173 compiling with mkmessage E-27 designating a Help key 7-166 designating a pathname 7-166 format of E-27 showhelp function 6-21, E-29 HELP keyword INPUT ARRAY statement 7-129 INPUT statement 7-123 MENU statement 7-149 OPTIONS statement 7-166, E-27 PROMPT statement 7-173 Help line 7-149, 7-154 Help menu 6-21, E-29 Help message creating and compiling 1-9, 1-38, E-27 displaying 1-8, 1-37, 6-22, 7-123, 7-129, 7-166 Hidden options of menus 7-152 High availability Intro-7 HOLD keyword, DECLARE statement 7-64 HOUR keyword DATETIME qualifier 3-10, J-2 INTERVAL qualifier 3-10, J-6 Hyphen ( - ) symbol comment indicator 2-4 delimiter in DATETIME values E-12 delimiter in INTERVAL values E-12 in USING format strings 2-45 in window border 4-13, I-6 range indicator in dbload files E-13

Index 11

I
i4gl command 1-6, 1-25, 4-61 i4gldemo script Intro-11, 1-6 Identifier defining 3-28, 4-54, 7-71 distinction between INFORMIX4GL and SQL 3-7 naming conventions 2-4, 4-54 PREPAREd statements 7-67, 7-109 scope of reference 2-4, 7-67, 7-172 IF statement 2-19 relationship to CASE 7-22 syntax and notes 7-118 Implicit transactions 3-6 IN keyword CREATE AUDIT statement 3-46, 7-39 CREATE DATABASE statement 3-43 CREATE TABLE statement 7-10, 7-50 LOCK TABLE statement 3-49, 7-146 SELECT statement 7-230 START DATABASE statement 3-43 INCLUDE attribute 4-57 definition of 4-35 guidelines for using 4-35 specifying values in 7-212 Index ascending and descending 7-53 auto_indexing 3-52 check and repair index files E-2 clustered 3-52, 7-12, 7-45 creating the index 7-44, E-22 filters 3-52, 7-194 guidelines for using 3-50 multiple-column 7-16, 7-44 NULL value 3-54 removing from a database 7-88 UNIQUE 7-44, 7-53, 7-139 with dbload utility E-20 INDEX keyword GRANT statement 7-115 REVOKE statement 7-187

INDEX PATH table access method 7-194 Indirect typing of program variables 7-71 infield function help messages E-29 ON KEY 7-126 syntax and notes 6-14, 7-134 infocmp utility I-24, I-27 informix user name E-6 INFORMIX-4GL as a report writer 5-3 as a screen-building utility 4-3 command file names 1-31, 1-61 language overview 2-3 versions Intro-3, 1-5 INFORMIXDIR environment variable C-7, E-30 INFORMIX-ESQL/C functions 1-32, 1-64 INFORMIX-OnLine database engine Intro-6, 7-6 INFORMIX-SE database engine Intro-6, 7-6 INFORMIX-SQL application development tool 4-63 INFORMIX-STAR add-on Intro-7 INFORMIXTERM environment variable C-7, I-1, I-20 INITIALIZE statement 2-17, 7-120 INPUT ARRAY statement 2-20 arr_curr function 6-7 infield function 6-14, 7-134 NOENTRY fields 4-37 scr_line function 6-18 set_count function 6-20 syntax and notes 7-129 table of functions in 7-135 terminating 7-132 INPUT ATTRIBUTE clause of OPTIONS statement 7-168 Input buffer 3-26, 7-139 Input files dbload utility E-11 LOAD statement 7-143 INPUT keyword INPUT statement 7-122 OPTIONS statement 7-166

INPUT NO WRAP keywords OPTIONS statement 7-166 INPUT statement 2-20 arr_count function 6-6 EXIT INPUT 7-96 infield function 6-14, 7-126 NOENTRY fields 4-37 syntax and notes 7-122 terminating 7-125 INSERT cursor closing 3-26, 7-25 declaring 3-25, 3-37, 7-64 flushing the insert buffer 7-25, 7-102 guidelines for using 3-25 opening 3-37, 7-156 putting a row in the insert buffer 7-177 Insert key 7-166, I-5, I-23 INSERT keyword dbload command file E-12 DECLARE statement 3-26, 7-64 GRANT statement 7-115, E-14 INPUT ARRAY statement 7-130 LOAD statement 7-143 OPTIONS statement 7-166 REVOKE statement 7-187 INSERT statement 3-12 DATETIME or INTERVAL values J-8 functions in 7-248 inserting through a view 3-59 running a PREPAREd 3-37 SERIAL columns in 7-139 syntax and notes 7-138 with NULL values 3-57 INSTRUCTIONS section of form specification definition of 4-51 DELIMITERS statement 4-52 screen arrays 4-55 SCREEN RECORD statement 4-54 screen records 4-54 INT data type 2-7, 3-8 Integer constant 2-5 INTEGER data type acceptable values 2-7, 3-8, 7-50 INT synonym 2-7, 3-8

12

Index

with database columns 3-8 with display fields 4-7 with variables 2-7, 7-71 Intentional blanks (in multiple-line fields) 4-48 Interactive Debugger Debugger path 1-50 description of Intro-4, 1-65 invoking 1-38, 1-53 Interactive mode bcheck utility E-3 dbload utility E-18 Interrupt key 2-23, 7-69, E-20 INTERRUPT keyword, DEFER statement 2-23, 7-69 Interrupt signal 2-23, 7-69 INTERVAL data type 2-9, J-5 acceptable values 7-51 entered as a character string J-8 entered as a literal value 4-30, J-6 in dbload input files E-12 manipulating arithmetically 2-36, J-9 using the UNITS keyword J-13 with database columns 3-10 with display fields 4-30 with variables 2-9, 7-71 INTO keyword dbload command file E-13 FETCH statement 3-17, 7-98 FOREACH statement 3-16 INSERT statement 7-139 LOAD statement 7-143 SELECT statement 3-29, 7-224, 7-245 INTO TEMP clause SELECT statement 7-8, 7-245 with INSERT statement 7-139 int_flag variable 2-23, 7-69 Inverse video (synonym for reverse) 4-58 INVISIBLE attribute 4-59, 7-77 Invoking 4GL Compiler 1-6, 1-32, 1-61 4GL programs 1-6, 1-30, 1-52 FORM4GL 1-17, 1-46, 4-63 Interactive Debugger 1-38, 1-59 Programmers Environment 1-6, 1-7, 1-36

IS keyword 2-13, 3-56, 7-60, 7-234 ISAM record number 3-62 Italics, in syntax statements Intro-10 items table in stores database Intro-11, A-3

L
LABEL statement GOTO 2-19, 7-114, 7-141, 7-213 syntax and notes 7-141 LAST keyword FETCH statement 3-23, 7-98 OPEN WINDOW statement 7-161 OPTIONS statement 7-167 REPORT statement 5-33 LEFT attribute 4-26 LEFT MARGIN statement 5-12 LENGTH keyword LENGTH( ) function 2-38, 6-16, 7-251 PAGE LENGTH statement 5-17 Less ( < ) than symbol in USING format strings 2-44 relational operator 2-13, 7-33 REVERSE attribute 4-42 LET statement 2-17 CLIPPED 2-27, 3-31 examples 2-38 syntax and notes 7-142 USING 2-46 with string expressions 2-8 Library functions (INFORMIX4GL) arg_val 6-4 arr_count 6-6 arr_curr 6-7 downshift 6-9 errorlog 6-13 err_get 6-10 err_print 6-11 err_quit 6-12 infield 6-14, 7-126, 7-134 length 6-16, 7-251 num_args 6-17 scr_line 6-18 set_count 6-20 showhelp 6-21 startlog 6-23 upshift 6-25 LIFO (last-in, first-out) queue 2-55 LIKE data type specification 7-138

J
Joins 4-63, 7-234 columns with the same name 7-235, G-1 in definition of a view 3-59 multiple joins 7-235, G-5 NULL column values 3-56, G-3 outer join 3-61, 7-235, G-1 self-join 7-235 stores database columns A-5

K
Kernel locking 3-50, 7-197 Key Accept key 7-34, 7-124, 7-166 arrow keys 7-35, 7-125 function keys 7-125, 7-133, 7-167 Help key 7-129, 7-166, E-27 Interrupt 2-23, 7-34, 7-152 Quit 2-23, 7-69 restricted 7-125 scrolling and editing 7-35, 7-166 used in screen arrays 7-131, 7-166 KEY keyword INPUT ARRAY statement 7-132 INPUT statement 7-123 MENU statement 7-149 OPTIONS statement 7-166 Keywords, notation in syntax statements Intro-10

Index 13

LIKE keyword DEFINE statement 2-10, 7-71 DISPLAY LIKE attribute 4-31 FORMONLY fields 4-19 GLOBALS statement 7-112 INITIALIZE statement 7-120 RECORD data type 2-9 SELECT statement 2-13, 7-231 VALIDATE LIKE attribute 4-45 VALIDATE statement 2-24, 7-211 WHERE clause 7-231 LINE keyword OPEN WINDOW statement 7-161 OPTIONS statement 7-165 SKIP statement 5-43 Line mode of a terminal 7-175 LINENO expression 5-48 LINES keyword NEED statement 5-38 SKIP statement 5-43 LOAD statement 3-29, 7-143 Local variables 2-4, 5-7 LOCK TABLE statement 3-40, 3-47 syntax and notes 7-146 Locking guidelines for using 3-47 row-level 3-48, 7-139, 7-146 table-level 3-49, 7-146, E-19 LOG keyword CREATE DATABASE statement 3-43 CREATE TABLE statement 7-50 SELECT statement 7-245 START DATABASE statement 3-43 Logging error messages 6-23, E-19 of temporary tables 7-50 transactions 3-43 LOOKUP attribute of PERFORM 4-63 Looping statements 5-4 FOR 2-18, 7-38, 7-104 FOREACH 2-18, 3-16, 7-106 WHILE 2-19, 3-27, 7-216 Lowercase characters DOWNSHIFT attribute 4-32, E-39 downshift function 6-9

in 4GL statements 2-3, 4-11 in syntax statements Intro-10 SHIFT attribute 4-57, E-39 UPSHIFT attribute 4-43, E-39 upshift function 6-25

M
MAGENTA attribute 4-26, 4-59, I-19 MAIN statement description 2-17 in source-code modules 1-33 syntax and notes 7-148 manufact table in stores database Intro-11, A-4 MARGIN keyword BOTTOM MARGIN statement 5-16 LEFT MARGIN statement 5-12 RIGHT MARGIN statement 5-13 TOP MARGIN statement 5-15 WORDWRAP function 5-40 MATCHES keyword, in WHERE clause 4-58, 7-8, 7-33, 7-232 MAX aggregate function 3-64, 5-46, 7-249 MDY function 2-39, 7-254 Menu options of Programmers Environment 1-7, 1-30 MENU statement CONTINUE MENU 7-38 description 2-19 EXIT MENU 7-96 help messages 7-151 syntax and notes 7-149 Menu-building utility 7-149 Menu, programmer-defined creating 7-149 displaying options 7-38, 7-151 naming menu options 7-150 requesting help from 7-151 selecting options 7-152 Message line 2-19, 7-154 MESSAGE LINE keywords OPEN WINDOW statement 7-161 OPTIONS statement 7-154, 7-165

Message numbers in help files E-27 MESSAGE statement 2-19 syntax and notes 7-154 MIN aggregate function 3-64, 5-46, 7-249 Minus ( - ) sign arithmetic operator 2-11, 4-25, 7-219 comment indicator 2-4 delimiter in DATETIME values 2-6, E-12 delimiter in INTERVAL values 2-6, E-12 in USING format strings 2-45 in window border 4-13, I-6 unary operator 2-5, 2-6, 4-25 MINUTE keyword DATETIME qualifier 3-10, J-2 INTERVAL qualifier 3-10, J-6 mkmessage utility 1-9, 1-38, E-27 MODE ANSI database comment indicators 2-4 description of 3-6 error handling 2-22 implicit transactions 3-6, 3-43 owner naming 3-7, 4-15 specifying 3-42 syntax checking 3-6, 3-64, 7-7 table access privileges 3-41 MODE ANSI keywords CREATE DATABASE statement 3-43, 7-41 START DATABASE statement 3-42, 7-200 MODE keyword CREATE DATABASE statement 3-43 LOCK TABLE statement 7-146 SET LOCK MODE statement 3-48, 7-197 START DATABASE statement 3-42 MODIFY keyword, ALTER TABLE statement 7-15 Modify option FORM Menu 1-15, 1-44, 4-61 MODULE Menu 1-9, 1-39 PROGRAM Menu 1-19, 1-49

14

Index

Module 2-18 compiling 1-13, 1-42 option of INFORMIX-4GL Menu 1-9, 1-38 running multi-module programs 1-13, 1-42, 1-65 MODULE Menu 1-26, 1-55 Module variables 2-4 MONEY data type acceptable values 3-9, 7-50 in dbload input files E-12 with database columns 3-9 with display fields 4-29, C-5 with variables 2-8, 7-71 MONTH keyword DATETIME qualifier 3-10, J-2 INTERVAL qualifier 3-10, J-5 MONTH( ) function 2-40, 7-9, 7-255 Multiple-column fields 4-21, 4-34, 4-42 Multiple-database queries Intro-7 Multiple-line fields 4-20, 4-47 Multiple-module programs, compiling 1-13, 1-27, 1-41, 1-50, 1-56, 1-64 Multiple-statement prepared objects 3-38, 7-172 Multiple-table forms 4-56 Multiple-table view 3-60, 7-58

N
Naming conventions column 3-6, 7-51 constraints 3-7, 7-49 database 3-6, 7-41 display fields 4-17, 4-18, 4-22 field tags 4-11 identifiers 2-4, 3-6 objects in a MODE ANSI database 3-7 table 3-6, 7-51 NEED statement in REPORT statement 5-38 New option FORM Menu 1-17, 1-46 MODULE Menu 1-12, 1-41

PROGRAM Menu 1-22, 1-51 NEWLINE character 4-47, E-11 NEXT FIELD clause INPUT ARRAY statement 7-130 Next key 7-166, I-5, I-23 NEXT keyword FETCH statement 3-22, 7-98 MENU statement 7-150 OPTIONS statement 7-166 NO keyword CREATE TABLE statement 7-50 OPTIONS statement 7-166 SELECT statement 7-245 syscolval table 4-57 NO WRAP keywords, OPTIONS statement 7-166 NOENTRY attribute 4-37 NORMAL attribute 4-59, 7-77, 7-154 NOT FOUND keywords WHENEVER statement 2-22, 7-213 NOT keyword ALTER INDEX statement 3-53, 7-12 Boolean operator 2-13, 3-55, 7-218 SELECT statement 7-238 SET LOCK MODE statement 7-197 WHERE clause 7-229 NOT NULL keywords ALTER TABLE statement 3-54, 7-14 CREATE TABLE statement 3-54 dbload utility E-14 dbupdate utility E-25 FORMONLY fields 4-19 SELECT statement 2-13, 7-228 NOTFOUND code, status variable 3-63 NOTFOUND keyword status after FETCH 3-17, 3-22 status after SELECT 3-63 NOUPDATE attribute of PERFORM 4-63 NULL keyword dbload command file E-13 INITIALIZE statement 2-15

NULL values aggregate functions 3-55, 3-64, 5-46, 7-250 assigning 7-120 definition of 2-5, 3-53 in Boolean expressions 2-14, 3-55, 7-118, 7-229 in columns 3-54, 7-144, 7-234 in display fields 4-19, 4-29, 4-40 in GROUP BY clause 3-56, 7-240 in joined columns 3-56, G-3 in number expressions 3-54 in ORDER BY clause 3-56 in string expressions 3-54, 4-29 in WHERE clause 3-55, 7-228 NOT NULL clause 3-54, 7-51, 7-228 truth tables 3-55 with dbload utility E-12 with INSERT 3-57 with UPDATE 3-57 WITHOUT NULL INPUT 4-7 Number expression 2-11 arithmetic operators in 2-11 formatting 2-44, 4-33 NULL values in 3-54 Number of rows processed 3-63 NUMERIC data type 2-8, 3-9 num_args function 6-17

O
O symbol Intro-11 Object file 1-35, 1-50, 1-72, E-30 Object, naming in MODE ANSI database 3-7 OF keyword AFTER GROUP OF control block 5-25 ARRAY data type 2-10 BEFORE GROUP OF control block 5-27 DECLARE statement 3-17, 7-64 DELETE statement 3-18, 7-73 UPDATE statement 3-19, 7-207 OFF keyword, SET EXPLAIN 7-194 ON EVERY ROW control block 5-31

Index 15

ON KEY clause DISPLAY ARRAY statement 7-60, 7-79 INPUT ARRAY statement 7-130 INPUT statement 6-22, 7-123 PROMPT statement 7-173 ON keyword CONSTRUCT statement 7-32 DISPLAY ARRAY statement 7-79 GRANT statement 7-115 PROMPT statement 7-173 REPORT statement 5-8 REVOKE statement 7-187 SET EXPLAIN statement 3-52, 7-194 ON LAST ROW control block 5-33 OnLine database engine Intro-6, 7-7, C-7 OPEN FORM statement 2-20 opening a closed form 7-28 syntax and notes 7-159 OPEN statement syntax and notes 7-156 USING clause 3-36, 7-157 with a SELECT cursor 3-16 with an INSERT cursor 3-26, 7-157 OPEN WINDOW statement 2-20 ATTRIBUTE clause 7-161 syntax and notes 7-160 Operating system invoking the Compiler from 1-32, 1-61 invoking the Programmers Environment from 1-25, 1-30, 1-54, 1-59 Operator arithmetic 2-11 range 7-34, 7-233 relational 2-13 string 2-12 UNION 7-246 OPTION keyword CREATE VIEW statement 3-60, 7-57 GRANT statement 7-116 MENU statement 7-150 Options of 4GL menus 7-150

OPTIONS statement 2-20 mkmessage utility E-27 syntax and notes 7-165 OR keyword Boolean operator 2-13, 3-55 COLOR attribute 4-25 in WHERE clause 3-56, 7-234 ORDER BY clause ASC 3-56, 7-243 DESC 3-56, 7-243 INSERT statement 7-139 multiple-column sorting 7-243 prohibited in view definition 7-58 REPORT statement 5-18, 5-25 SELECT statement 7-243 with NULL values 3-56 orders table in stores database Intro-11, A-3 OTHERWISE keyword CASE statement 7-21 Outer joins 3-61, G-1 OUTER keyword, SELECT statement 3-62, 7-8, 7-218, 7-226, G-3 OUTPUT section of REPORT statement 5-9 BOTTOM MARGIN 5-16 LEFT MARGIN 5-12 PAGE LENGTH 5-17 REPORT TO 5-10 REPORT TO PRINTER 5-10 RIGHT MARGIN 5-13 syntax 5-9, 7-184 TOP MARGIN 5-15 OUTPUT TO REPORT statement 2-21 guidelines for using 5-4 syntax and notes 7-170 Overflow of a display field 2-46 Owner naming 3-7, 7-226 ALTER TABLE statement 7-15 and system catalogs 3-8 CREATE SYNONYM statement 7-47 CREATE TABLE statement 7-51 CREATE VIEW statement 7-57 FORM4GL specification 4-15 INITIALIZE statement 7-120

START DATABASE statement 7-200 VALIDATE statement 7-211 Owner of an object in a MODE ANSI database 4-4, 4-60, 7-16, 7-35

P
PAGE HEADER control block 5-29, 5-34 PAGE keyword FIRST PAGE HEADER control block 5-29 PAGE HEADER control block 5-34 PAGE LENGTH statement 5-17 PAGE TRAILER control block 5-36 SKIP statement 5-43 PAGE LENGTH statement 5-17 PAGE TRAILER control block 5-36 PAGENO expression 5-49 Pages of a help file message E-28 of a report 5-9 of a screen form 4-9, 4-63 of menu options 7-150 Parameters of functions 2-56, 7-110 Parentheses in syntax statements Intro-10 in USING format strings 2-45 Pattern matching query by example 7-33 with equal ( = ) sign 7-33 with LIKE 2-13, 7-231 with MATCHES 2-13, 7-232 PAUSE statement, REPORT statement 5-39 P-code compiler, function 1-61 P-code runner 1-61 customized 1-68, 1-69 Interactive Debugger 1-59 specifying name and location 1-50 P-code version number 1-62, 1-64 PERCENT aggregate function 5-46

16

Index

PERFORM (INFORMIX-SQL) screens with INFORMIX4GL 4-3, 4-63 Period ( . ) symbol delimiter in DATETIME values 2-6, E-12 delimiter in INTERVAL values 2-6, E-12 in help message source files E-27 in USING format string 2-45 prefix separator 2-24, 4-14 range operator 7-34 PICTURE attribute 4-38, 4-57 PIPE keyword REPORT TO statement 5-10 START REPORT statement 7-202 Planned_Compile option, PROGRAM Menu 1-23, 1-52 Plus ( + ) sign arithmetic operator 2-11, 7-219 in USING format strings 2-45 in window border 7-163, I-6 unary operator 2-5, 2-6 Popping functions (C language) 2-55 Pound ( # ) sign comment indicator 2-3, I-3 in FORMAT format strings 4-33 in PICTURE format strings 4-38 in USING format strings 2-44 PREPARE statement 3-28 executing 3-33, 7-94 guidelines for using 3-28 multiple SQL statements 3-38, 7-172 syntax and notes 7-171 using placeholders for values 3-30 with a character string 3-30 with a character variable 3-31 Preprocessor, invoking 1-31, 1-32 Previous key 7-166, I-5, I-23 PREVIOUS keyword FETCH statement 3-23, 7-98 OPTIONS statement 7-166 PRINT FILE statement in reports 5-42 PRINT statement

CLIPPED 2-27 COLUMN 2-29 REPORT statement 5-40 USING 2-48 PRINTER keyword REPORT TO statement 5-10 START REPORT statement 7-202 PRIOR keyword, FETCH statement 3-17, 7-98 PRIVILEGES keyword 7-115 Process isolation Intro-7 Program array array of records 2-10 arr_count function 6-6 arr_curr function 6-7 defining 2-10, 7-71 displaying rows in 7-79 inserting rows 7-131 set_count function 6-20 table of functions for 7-135 Program examples that call C functions 1-70, 2-57 Program execution commencing 1-59, 1-65, 6-4, 6-17 from the command line 1-6, 6-4 programs that call C functions 1-34, 1-66 terminating 6-12, 7-97 with the Interactive Debugger 1-65, 1-72 Program features assignment statements 2-17 calling C functions 1-66, 2-55, 7-19 commenting 2-3 compiler 1-25, 1-32, 1-39 compiling through Programmers Environment 1-10, 4-60 compiling, at operating system level 1-61 conditional statements 4-25, 7-21, 7-118 error messages 2-21, 6-10, E-29 executing a non-4GL process 7-191 expressions 2-11 functions 2-24, 2-55, 6-3, 7-110 help messages 6-21, 7-166, E-27 identifiers 2-4

INFORMIX-4GL language overview 2-3 lettercase sensitivity 4-11 looping statements 3-24 MAIN program block 2-17, 7-148 menus 7-149 multi-module programs 1-13, 1-41 owner naming 4-15 program arrays 2-10 program flow statements 2-18, 7-5 records 4-54, 7-71, 7-138 reports 2-21, 5-3, 7-184 running, at operating system level 1-64 screen interaction statements 2-19, 7-165 statement types 2-16, 3-10, 7-5 transactions 3-42 types of program modules 1-10, 1-21, 1-29, 1-32, 1-50, 1-69 Program flow statements 2-18, 7-5 Program module, definition of 2-18 Program organization statements 2-17, 7-5 Program records 7-72, 7-138 Program specification database 1-18, 1-48 Programmers Environment accessing 1-6, 1-7, 1-37 COMPILE FORM Menu 1-16, 1-45 COMPILE MODULE Menu 1-10, 1-39 COMPILE PROGRAM Menu 1-22, 1-51 compiling a form 1-27, 1-56, 4-61 compiling a program 1-12, 1-27, 1-41, 1-56 correcting errors in a program 1-11, 1-40 creating a default form 4-61 Debug option, MODULE Menu 1-42 Debug option, PROGRAM Menu 1-53 defining a program 1-26, 1-55 definition of 1-6

Index 17

Drop option, PROGRAM Menu 1-24 Exit option, FORM Menu 1-18, 1-47 Exit option, MODULE Menu 1-14, 1-43 Exit option, PROGRAM Menu 1-24, 1-53 files displayed 1-26, 1-64 FORM Menu 1-14, 1-43, 4-61 Generate option, FORM Menu 1-16, 1-46 in C Compiler version of 4GL 1-7 in Rapid Development System 1-36 INFORMIX-4GL Menu 1-8, 1-37 invoking the Debugger 1-38, 1-53 menu options 1-31, 1-61 modifying a form specification file 1-15, 1-44 MODULE Menu 1-9, 1-38 NEW FORM Menu 1-17, 1-46 NEW MODULE Menu 1-12, 1-41 NEW PROGRAM Menu 1-22, 1-51 Planned_Compile option, PROGRAM Menu 1-23, 1-52 PROGRAM Menu 1-18, 1-48 Program_Compile option, MODULE Menu 1-13, 1-41 QUERY LANGUAGE Menu 1-25, 1-54 Run option, MODULE Menu 1-13, 1-42 Run option, PROGRAM Menu 1-24, 1-52 Undefine option, PROGRAM Menu 1-53 Program_Compile option, MODULE Menu 1-13, 1-41 PROMPT LINE keywords OPEN WINDOW statement 7-161 OPTIONS statement 7-165 Prompt line of a screen form 7-162 PROMPT statement 2-19 syntax and notes 7-173 Pseudo-code (= p-code) 1-5

PUBLIC keyword GRANT statement 3-41, 7-52, 7-116 REVOKE statement 7-52, 7-188 Pushing functions (C language) 2-55 PUT statement and the SQLCA record 3-28, 7-178 and the status variable 3-28, 7-178 FROM clause 3-38 guidelines for using 3-26, 7-26 syntax and notes 7-177

QUIT keyword, DEFER statement 7-69 quit_flag variable 2-23, 7-69 Quotation ( " ) marks around character pointer 1-68 around character strings 2-5, 4-36 around date-time value 2-6, 4-29 around format strings 2-44, 2-46, 4-33, 4-38 around pathnames 7-39, 7-50, 7-200

R
r4gl command 1-6, 1-54, 4-61 r4gldemo script Intro-11, 1-6 Range of values COLOR attribute 4-25 dbload utility E-14 INCLUDE attribute 4-35 query by example 7-34 upscol utility 4-58, E-41 WHERE clause 7-229 Rapid Development System version of 4GL Intro-3, 1-5, 1-36 RDS (= Rapid Development System) 1-5 REAL data type 2-8, 3-9 Record definition of 2-9, 7-71 in an array 4-54, 7-192 passing to a function 7-111 SQLCA global record 3-63 with INSERT 7-138 RECORD keyword defining program records 2-9, 7-71 defining screen arrays 4-55 defining screen records 4-54 defining variables 7-71 LIKE keyword 2-9, 7-71 Records in data files 7-143, 7-203, E-12 RECOVER TABLE statement 3-46, 7-179 Recovery procedures Intro-7, 3-42 RED attribute 4-26, 4-59, 7-77, I-19

Q
Query by example CONSTRUCT 7-33 PREPARE 3-30 table of operators 7-33 using the alternation operator 7-33 using the range operator 7-34 using wildcard characters 7-34 Query optimizer 3-52, 7-194 QUERYCLEAR attribute of PERFORM 4-63 Querying the database compound queries 7-246 cursors 3-13, 7-64, 7-156 distributed across databases Intro-7 joins 3-51, 4-63, 7-234, G-1 query by example 7-32 relational operators 7-220 searching for rows with NULL values 3-56 subqueries 3-56, 7-207, 7-237 through views 3-58 with SELECT 7-218 Question ( ? ) mark placeholder in PREPAREd statements 3-30, 7-94, 7-171, 7-178 wildcard 7-34, 7-232 Quick Reference Card Intro-3 Quit key 2-23, 7-69

18

Index

Relational operators 2-13, 4-25, 7-220 RELATIVE keyword FETCH statement 3-17, 7-98 RENAME COLUMN statement 3-12 syntax and notes 7-181 RENAME TABLE statement 3-11 syntax and notes 7-182 Report generation statements 2-21, 7-5 REPORT statement 2-18 aggregate functions 5-44 control blocks 5-23 DEFINE section 5-5, 5-7 displaying a report 5-9 END REPORT keywords 5-5 FORMAT section 5-5, 5-20 grouping data 5-23 ORDER BY section 5-5, 5-18 ORDER EXTERNAL BY 5-18 OUTPUT section 5-5, 5-9 PRINT statement 5-40 REPORT keyword 5-6 running a report 5-4, 7-202 SKIP statement 5-43 statements in a report routine 5-37 structure 5-5 syntax and notes 7-184 REPORT TO statement 5-10 Report writer 5-3 Reports, programmer-defined aggregate functions 5-26 calculations on groups 5-47 counting rows 5-46 default layout 5-21 features 5-3 formatting 5-20, 5-23, 7-184 minimal report 5-6 output of a report 5-9 piping a report to a program 5-10 printing data 5-40 running a report 5-4 sending output to a file 5-10 sorting data 5-18, 7-185 starting report processing 7-202 steps for creating 5-4 REQUIRED attribute 4-40

Reserved lines Comment line 4-27, 7-165 default settings 7-161 Error line 2-19, 2-23, 6-11, 6-12, 7-162, 7-165 Form line 2-20, 7-162, 7-166 Message line 2-19, 7-165 Prompt line 2-19, 7-165 Reserved words listing D-1 RESOURCE access privilege 7-116 RESOURCE keyword GRANT statement 3-41, 7-116 REVOKE statement 7-187 Return key 7-166 RETURN keyword FUNCTION statement 7-110 RETURN statement 7-186 RETURNING keyword CALL statement 2-56, 7-19 RUN statement 7-191 REVERSE attribute 4-26, 4-59, I-9 description of 4-42 multiple-column 4-21 REVOKE statement 3-40 DBA 3-41 syntax and notes 7-187 RIGHT attribute of PERFORM 4-63 RIGHT MARGIN statement 5-13 Ring menu 7-150 ROLLBACK WORK statement restoring previous database 3-42 syntax and notes 7-189 ROLLFORWARD DATABASE statement definition of 3-42 recovering a database 3-45 syntax and notes 7-190 Row 3-5 deleting from a table 3-18, 7-73 determining row length E-24 duplicates in a view 3-60 inserting into a table 7-138 locking 3-48, 7-99, 7-139 ROWID 3-62 unlocking 3-48 updating 3-19, E-38

ROW keyword EVERY ROW statement 5-21 INPUT ARRAY statement 7-130 ON EVERY ROW control block 5-31 ON LAST ROW control block 5-33 Row number in a database table 3-62 in a program array 6-7, 6-20 in a screen array 4-55, 6-18 ROWID value 3-62, 3-64 ROWS keyword, OPEN WINDOW statement 7-160 Run menu option 1-31, 1-61 Run option MODULE Menu 1-13, 1-42 PROGRAM Menu 1-24, 1-52 RUN statement 2-19, 7-191 Runner, creating a customized 1-69 Runner, invoking 1-5, 1-50, 1-61 Running a 4GL program command line 1-6, 1-34 that calls C functions 1-34, 1-72 using Debugger 1-61, 7-7 Run-time errors 2-21, 7-213

S
Schema language 7-10 Schema replication, using dbschema E-22 Scope of reference of identifiers 2-5 Screen array 7-32, 7-75 definition of 4-55 format of 4-12, 4-56 identifying the current row 6-7, 6-18 keys for scrolling and editing 7-131 scrolling rows of data 7-192 table of functions for 6-3, 7-135 Screen display characteristics changing attributes 4-59, 7-36, 7-77, 7-81, 7-83, 7-93, 7-127, 7-136, 7-155, 7-168, 7-175 clearing the screen 7-23, I-4, I-22

Index 19

default screen attributes 4-56, E-40 screen coordinates 4-8, 7-76, 7-161 setting up screen attributes 4-22 table of color and intensity values 4-57 Screen form 4-5 clearing values in the form 7-23 closing 7-28 dimensions 4-6, 4-8, 7-161 displaying 7-83, 7-165 displaying values in fields 7-75 entering values in fields 7-32 identifying the current field 6-14 opening a 7-159 specifying from the Programmers Environment 1-14, 1-43, 4-61 Screen interaction statements 2-19, 7-5 SCREEN keyword CLEAR statement 7-23 CURRENT WINDOW statement 7-60 INSTRUCTIONS section of form specification 4-4, 4-54 SCREEN section of form specification 4-8 Screen record 7-32, 7-75 default screen record 4-54 definition of 4-54 moving rows through a screen array 7-192 SCREEN RECORD keywords 4-54 SCREEN section of form specification definition of 4-8 display field 4-10 field delimiters 4-11, 4-52 field tags 4-10 field width 4-11 for a multiple-table form 4-6 graphics characters 4-12 screen page layout 4-9 Screen-building utility 4-3 SCROLL keyword DECLARE statement 3-14, 7-64 SCROLL statement 2-21, 7-192 scr_line function 6-18, 7-135

SECOND keyword DATETIME qualifier 3-10, J-2 INTERVAL qualifier 3-10, J-6 SELECT clause ALL 7-222 display label 7-8, 7-222 DISTINCT and UNIQUE keywords 7-222 join conditions 7-234, G-1, G-4 syntax and notes 7-222 SELECT cursor advancing 3-17 closing 3-17, 7-25 declaring 3-14, 7-64 opening 3-16, 7-156 syntax and notes 3-13, 7-64 SELECT keyword dbload command file E-12 DECLARE statement 3-14, 7-64 GRANT statement 3-41, 3-60, 7-115, 7-204 REVOKE statement 3-41, 7-187 SELECT statement aggregate functions in 7-249 arithmetic operators in 7-219 assigning a cursor 3-14, 7-64 constructing with LET 7-172 creating temporary tables 7-8, 7-245 DATETIME or INTERVAL values J-15 defining a view 3-58, 7-57 definition of 3-12, 7-193 displaying results 5-3 distributed across databases Intro-7 estimating CPU cost 3-52, 7-194 expression in 7-219 FROM clause 7-226 functions in 2-24, 7-248 GROUP BY clause 7-8, 7-240 HAVING clause 7-242 in a DECLARE statement 7-64 in an INSERT statement 7-138 in an UNLOAD statement 7-203 INTO clause 3-29, 7-99, 7-107, 7-224 INTO TEMP clause 3-58, 7-8, 7-245

joining columns with 3-51, 7-234 LENGTH function 2-38, 7-251 ORDER BY clause 3-18, 7-243 overview of clauses 7-220 relational operators 7-220 SELECT clause 7-222 self-join 7-235 singleton SELECTs 7-224 syntax and notes 7-193, 7-218 UNION operator 7-246 using multiple tables 7-220 WHERE clause 7-228 with an outer join 3-62, 7-235, G-1 with multiple joins 7-235, G-5 with subqueries 3-56, 7-237 Semicolon ( ; ) symbol in multiple-column display fields 4-21 in the description of a display field 4-16 statement terminator 7-172, E-14 SEQUENTIAL SCAN access method 7-194 SERIAL data type acceptable values 3-9, 7-51 INSERT statement 4-37, 7-139 program variables 2-9 retrieved by SQLCA.SQLERRD[2] 3-63 UPDATE statement 7-207 with database columns 3-9 with display fields 4-19, 4-37 SET EXPLAIN statement 3-52 syntax and notes 7-194 with joins G-10 SET keyword, UPDATE statement 7-206 SET LOCK MODE statement 3-48, 7-197 kernel locking 3-50 set_count function guidelines for using 7-80 syntax and usage 6-20 with INPUT ARRAY 7-135 sg1 terminal specification 7-77, 7-127, 7-136, 7-176, I-4, I-18 SHARE keyword LOCK TABLE statement 3-49, 7-146

20

Index

Shared memory Intro-6, 3-48, 7-197 SHIFT attribute 4-57 showhelp function 6-21, E-29 Single-field INTERVAL value 2-6, 4-30 SIZE keyword, form specification 4-9 SKIP statement in reports 5-43 SLEEP statement 2-19, 7-199 SMALLFLOAT data type acceptable values 2-8, 3-9, 7-50 REAL synonym 2-8, 3-9 with database columns 3-9 with FORMAT attribute 4-33 with variables 2-8, 7-71 SMALLINT data type acceptable values 2-7, 3-8, 7-50 with database columns 3-8 with variables 2-7, 7-71 SOME keyword, SELECT statement 7-237 Sorting data DATE columns 7-52 in a report 5-18 in an index 7-12 multiple-column sorting 7-243 with NULL values 3-56 with ORDER BY 5-25, 7-243 Source modules 1-32, 1-61, 1-63 Source path 1-50, C-6 SPACE keyword 5-50 Spacebar 7-150 Spaces in WORDWRAP fields 5-52 SPACES keyword 5-50 sqexplain.out file 3-52, 7-194 SQL ALTER INDEX statement 3-12, 7-12 ALTER TABLE statement 3-11, 7-14 BEGIN WORK statement 3-43, 7-18 CLOSE DATABASE statement 3-11, 7-27 CLOSE statement 3-17, 3-26 COMMIT WORK statement 3-43, 7-31

CREATE AUDIT statement 3-45, 7-39, 7-179 CREATE DATABASE statement 3-11, 7-41 CREATE INDEX statement 3-12, 7-44 CREATE SCHEMA AUTHORIZATION statement 7-10 CREATE SYNONYM statement 3-11, 7-47 CREATE TABLE statement 3-11, 7-49 CREATE VIEW statement 3-11, 7-57 DATABASE statement 3-11, 7-62 DECLARE statement 3-14, 3-26, 3-29, 7-64 DELETE statement 3-12, 7-73 DROP AUDIT statement 3-45, 7-85, 7-179 DROP DATABASE statement 3-11, 7-86 DROP INDEX statement 3-12, 7-88 DROP SYNONYM statement 3-12, 7-89 DROP TABLE statement 3-11, 7-90 DROP VIEW statement 3-11, 7-91 EXECUTE statement 3-28, 7-94 FETCH statement 3-16, 7-98 FLUSH statement 3-26, 7-102 FOREACH statement 3-16 FREE statement 3-39, 7-109 GRANT statement 3-40, 7-115 INSERT statement 3-12, 7-138 LOAD statement 3-12, 7-143 LOCK TABLE statement 3-40, 7-146 OPEN statement 3-16, 3-26 PREPARE statement 3-28, 7-171 PUT statement 3-26, 7-177 RECOVER TABLE statement 3-46, 7-179 RENAME COLUMN statement 3-12, 7-181 RENAME TABLE statement 3-11, 7-182

REVOKE statement 3-40, 7-187 ROLLBACK WORK statement 7-189 ROLLFORWARD DATABASE statement 7-190 SELECT statement 3-12, 7-64, 7-193, 7-203, 7-218 SET EXPLAIN statement 7-194 SET LOCK MODE statement 7-197 START DATABASE statement 7-200 UNLOAD statement 3-12, 7-203, E-11 UNLOCK TABLE statement 3-40, 7-205 UPDATE statement 3-12, 7-206 UPDATE STATISTICS statement 3-12, 7-210 WHENEVER statement 2-21, 7-213 SQL language 3-5 accessing from the Programmers Environment 1-25, 1-54 ambiguity with INFORMIX-4GL identifiers 3-7 audit trails 3-45, 7-39, 7-85, 7-179 data access statements 3-40, 7-6 data definition statements 3-11, 7-6 data integrity statements 3-42, 7-6 data manipulation statements 3-12, 7-6 dynamic management statements 3-28 identifiers 3-6, 3-28 interactive query language 1-8, 1-37, 3-5, 4-63 statements supported only on INFORMIX-SE 7-6 testing statement execution 3-63 transactions 3-42 update notes for Version 1.10 users 3-54 SQL version number 1-33, 1-62 SQLAWARN characters 3-6, 3-64, 7-213

Index 21

SQLCA record definition of 3-63 examined by WHENEVER 2-22 set by CLOSE 3-28 set by FLUSH 3-28 set by PUT 3-28, 7-178 SQLAWARN 3-6, 3-64, 7-213 SQLCODE 3-17, 3-63, 7-145, 7-178 SQLERRD 3-28, 3-63, 7-25, 7-145, 7-157 sqlconv utility E-31 SQLERROR keyword 7-213 SQLEXEC environment variable C-7 SQLWARNING keyword 7-213 Stack, in calling C functions 2-55 START DATABASE statement 3-42 syntax and notes 7-200 WITH LOG IN 3-43 START REPORT statement 2-21 directing output 5-10 syntax and notes 7-202 startlog function 2-22, 6-23 state table in stores database Intro-12, A-4 Statement identifier 3-28, 7-94, 7-109 Statement label 7-114, 7-141, 7-213 Statement syntax ALTER INDEX 7-12 ALTER TABLE 7-14 BEGIN WORK 7-18 CALL 7-19 CASE 7-21 CLEAR 7-23 CLOSE 7-25 CLOSE DATABASE 7-27 CLOSE FORM 7-28 CLOSE WINDOW 7-30 COMMIT WORK 7-31 CONSTRUCT 7-32 CONTINUE 7-38 CREATE AUDIT 7-39 CREATE DATABASE 7-41 CREATE INDEX 7-44 CREATE SYNONYM 7-47 CREATE TABLE 7-49 CREATE VIEW 7-57 CURRENT WINDOW 7-60

DATABASE 7-62 DECLARE 7-64 DEFER 7-69 DEFINE 7-71 DELETE 7-73 DISPLAY 7-75 DISPLAY ARRAY 7-79 DISPLAY FORM 7-83 DROP AUDIT 7-85 DROP DATABASE 7-86 DROP INDEX 7-88 DROP SYNONYM 7-89 DROP TABLE 7-90 DROP VIEW 7-91 ERROR 7-92 EXECUTE 7-94 EXIT 7-96 FETCH 7-98 FINISH REPORT 7-101 FLUSH 7-102 FOR 7-104 FOREACH 7-106 FREE 7-109 FUNCTION 7-110 GLOBALS 7-112 GOTO 7-114 GRANT 7-115 IF 7-118 INITIALIZE 7-120 INPUT 7-122 INPUT ARRAY 7-129 INSERT 7-138 LABEL 7-141 LET 7-142 LOAD 7-143 LOCK TABLE 7-146 MAIN 7-148 MESSAGE 7-154 OPEN 7-156 OPEN FORM 7-159 OPEN WINDOW 7-160 OPTIONS 7-165 OUTPUT TO REPORT 7-170 PREPARE 7-171 PROMPT 7-173 PUT 7-177 RECOVER TABLE 7-179 RENAME COLUMN 7-181 RENAME TABLE 7-182

REPORT 7-184 RETURN 7-186 REVOKE 7-187 ROLLBACK WORK 7-189 ROLLFORWARD DATABASE 7-190 RUN 7-191 SCROLL 7-192 SELECT 7-193, 7-218 SET EXPLAIN 7-194 SET LOCK MODE 7-197 SLEEP 7-199 START DATABASE 7-200 START REPORT 7-202 UNLOAD 7-203 UNLOCK TABLE 7-205 UPDATE 7-206 UPDATE STATISTICS 7-210 VALIDATE 7-211 WHENEVER 7-213 WHILE 7-216 Statement type assignment 2-17, 7-5 cursor manipulation 3-13, 7-6 data access 3-40, 7-6 data definition 3-11, 7-6 data integrity 3-42, 7-6 data manipulation 3-12, 7-6 data validation 2-23 dynamic management 3-28, 7-6 error and exception handling 2-21 program flow 2-18, 7-5 program organization 2-17, 7-5 report generation 2-21, 7-5 screen interaction 2-19, 7-5 variable definition 2-17, 7-5 status variable 2-22 definition of 3-63 NOTFOUND code 2-22, 3-17, 3-22, 7-99, 7-213 with cursors 3-28 with err_get function 6-10 with err_print function 6-11 with err_quit function 6-12 with INITIALIZE 7-121 with VALIDATE 7-212 STEP keyword, FOR statement 7-104

22

Index

stock table in stores database Intro-11, A-4 STOP keyword, WHENEVER statement 7-213 stores database customer table Intro-11, A-2 data values A-9 items table Intro-11, A-3 join columns A-5 manufact table Intro-11, A-4 orders table Intro-11, A-3 overview A-1 state table Intro-12, A-4 stock table Intro-11, A-4 structure of tables A-2, A-5 tables in Intro-11, A-2 String expression 2-12 CLIPPED keyword 2-27 concatenation operator 7-172 constants 2-5 length 2-38, 7-251 NULL values in 4-19 substring 2-12, 4-18 table of operators 2-12 USING keyword 2-44 Structure definition file, function 1-66 Subquery 3-56, 3-59, 7-222, 7-237, 7-247 Subscript evaluating with cursors 7-67 of a CHAR column 4-18, 7-220 Substring 2-12, 4-18, 7-142 SUM aggregate function 2-48, 3-64, 5-46, 7-249 Synonym for a table 3-11, 7-47, 7-226, E-22 removing a synonym 3-12, 7-89 rules for owner naming 3-7 Syntax checking, ANSI 1-32, 1-62, 3-6 Syntax conventions Intro-9 Syntax of command line to compile a 4GL source file 1-32, 1-61 syscolatt table 4-56 changing color names 4-58, I-19 color and intensity values 4-57, E-40 creating with upscol 4-60, E-37

schema 4-57 use by FORM4GL 4-17, 4-56 with DISPLAY LIKE 4-31 syscolval table 2-24, 4-56 as used by INITIALIZE 4-58, 7-121 comparing values of variables 7-211 creating with upscol 4-60, E-37 data validation 2-23, 4-58, 7-211 schema 4-57 use by FORM4GL 4-17, 4-56 with VALIDATE LIKE attribute 4-45 syspgm4gl files 1-18, 1-48 System catalogs creating 3-11, 7-41 described 3-5, B-1 querying when MODE ANSI 3-8 syscolauth B-3 syscolumns 3-58, 7-138, B-2 sysconstraints 7-16, 7-53, B-5 sysdepend B-4 sysindexes B-3 syssynonyms B-4 syssyntable B-5 systabauth B-3 systables 4-15, 7-210, B-2 sysusers B-4 sysviews 3-58, B-5 updating 3-12

T
Table 3-5 access methods 3-52, 7-194 access privileges 3-41, 7-115, E-22 adding a column 7-14 adding a constraint 7-16 adding a row 7-138, 7-143, E-11 alias for table name 4-14, 4-60, 7-35, 7-226 audit trails 3-42, 7-39 changing the data type of a column 7-14 creating 7-49, E-22 creating a synonym 7-47, E-22 current 4-63

display label 7-223 dominant 3-62, G-2 filename 7-50, E-2 guidelines for indexing 3-51 joining tables 3-52, 7-234, A-5, G-2 locking 3-49, 7-146, 7-208, E-19 modifying a row 3-59, 7-206 naming conventions 3-6, 7-51 not logging temporary 7-50 outer join 3-61, 7-235, G-1 removing a column 7-14 removing a constraint 7-16 removing a synonym 3-12, 7-89 removing a table 7-90 renaming 7-182 revoking user access 7-188 rules for owner naming 3-7 structure in stores database A-2 subservient 3-62, G-2 temporary 3-58, 7-223, 7-245, 7-247 unlocking 3-40, 3-47, 7-205 TABLES section of form specification definition of 4-4, 4-14 Tape block size E-6 TEMP keyword CREATE TABLE statement 7-10, 7-49 SELECT statement 3-58, 7-8, 7-245 termcap file 4-13, I-2 TERMINFO environment variable I-20, I-25 terminfo files 4-13, I-20 TEXT data type Intro-7 Text editor 1-11, 1-15, 1-31, 1-40, 1-45, 1-61 THEN keyword, IF statement 7-118 THROUGH keyword 2-15, 4-55 THRU keyword 2-15, 4-55 TIME function 2-41 TO keyword ALTER INDEX statement 3-53, 7-12 CURRENT function 2-30, 7-258 DATETIME literals 2-6, 4-30, J-2 DISPLAY ARRAY statement 7-79

Index 23

DISPLAY statement 2-15 EXTEND function 2-35, 7-260 GRANT statement 3-32, 7-115 INCLUDE attribute 4-35 INITIALIZE statement 2-15, 7-120 INTERVAL literals 2-6, 4-30, J-5 RENAME COLUMN statement 7-181 RENAME TABLE statement 7-182 REPORT TO statement 5-10 SET LOCK MODE statement 3-50, 7-197 SKIP statement 5-43 START REPORT statement 7-202 UNLOAD statement 7-203 WHENEVER statement 7-213 TODAY function 2-42, 3-65, 4-30 TOP MARGIN statement 5-15, 5-29 TOP OF PAGE keywords 5-43 TRAILER keyword, REPORT statement 5-36 Transaction committing modifications 3-42, 7-31 comparison with audit trails 3-47 cycle 3-43 definition of 3-42 explicit 3-44, 7-41, 7-200 implicit 3-43, 7-41, 7-200 log 3-43, 7-42, 7-200 log file maintenance 3-45 recovering transactions 3-42, 7-190 row locking 3-44, 7-139 singleton 3-44, 7-139 starting 3-44, 7-18 statements for specifying 3-42 undoing modifications 3-42, 7-189 usage in MODE ANSI 3-43 Transfer of database files E-6, E-11 TRUE (Boolean constant) 2-5, 3-55, 4-25 Truncation of data 3-64, 4-48, 7-80, E-15 Truth values 2-5, 3-55, 7-237, 7-238

Twenty-Minute Guide Intro-3 TYPE keyword, FORMONLY fields 4-19

U
Undefine option, PROGRAM Menu 1-53 UNDERLINE attribute 4-26, 4-59, I-9 UNION operator 3-58, 7-58, 7-246 UNIQUE constraint 7-139, E-14 UNIQUE keyword aggregate functions 7-250 ALTER TABLE statement 7-14 CREATE INDEX statement 7-44 CREATE TABLE statement 7-49 SELECT statement 7-8, 7-222 UNITS keyword 2-43, 4-30, J-13 SELECT statement 7-8 UNIX permissions E-14 UNKNOWN (Boolean constant) 2-14, 3-55 UNLOAD statement 3-29, 7-203, E-11 UNLOCK TABLE statement 3-40, 3-47 syntax and notes 7-205 UP keyword SCROLL statement 7-192 syscolval table 4-57, E-39 UPDATE keyword DECLARE statement 3-17, 7-64 GRANT statement 3-41, 7-115 REVOKE statement 7-187 UPDATE STATISTICS statement 7-210 UPDATE statement data conversion in 7-208 DATETIME or INTERVAL values J-15 examples 3-18 functions in 7-248 locking rows 3-48 subqueries 7-207 syntax and notes 7-206 updating through a view 3-59

WHERE CURRENT OF clause 3-19 with NULL values 3-57 UPDATE STATISTICS statement 3-12, 7-210 UPDATE SYSCOL Menu (upscol) E-37 Uppercase characters DOWNSHIFT attribute 4-32, E-39 downshift function 6-9 in 4GL statements 2-3, 4-11 in syntax statements Intro-10 SHIFT attribute 4-57, E-39 UPSHIFT attribute 4-43, E-39 upshift function 6-25 upscol utility 2-24, 4-59, E-37 UPSHIFT attribute 4-43, 7-35, E-39 upshift function 6-25 USER function 3-65, 7-219 User status and privileges 3-41 USING keyword DISPLAY statement 7-76 EXECUTE statement 3-33, 7-94 OPEN statement 3-36, 7-156 PRINT statement 2-47, 5-40 string operator 2-44 Utility programs bcheck E-2 dbexport E-6 dbload E-11, E-33 dbschema E-22 dbupdate E-25 mkmessage E-27 sqlconv E-31 upscol 2-24, 4-56, E-37

V
V command-line option 1-33, 1-62 VALIDATE LIKE attribute 4-15, 4-45 VALIDATE Menu (upscol) E-39 VALIDATE statement 2-24, 4-58, 7-211 VALUES keyword dbload command file E-14 INSERT statement 7-138 VARCHAR data type Intro-7

24

Index

Variable 2-6 as a parameter 2-17, 7-110 binding to database and forms 2-14 data types 2-7, 7-71 declaring a 2-4, 5-5, 7-71 global 2-4, 7-112 in REPORT statement 5-5 int_flag 2-23, 7-69 local 2-4, 7-110 module 2-4 naming conventions 2-4 quit_flag 2-23, 7-69 scope of reference 2-4 statements for assigning values 2-17 statements for defining 2-17 status variable 2-22, 3-63 with the same name 7-111 Variable definition statements 7-5 VERIFY attribute 4-46, 4-57 Version 1 database conversion to Version 2 E-25 Version numbers of SQL software 1-33, 1-62 Versions of 4GL Intro-3, 1-5 Vertical ( | ) bar field separator in files 7-203, E-17 field separator in forms 4-53 graphics character 4-13, I-6, I-25 in termcap specifications I-3 in window border 7-163, I-6 syntax convention Intro-10 with CONSTRUCT 7-33 View access privileges 3-60, 7-117, E-22 creating 3-58, 7-57, E-22 creating a synonym 7-47, E-22 data constraints 3-60 definition and uses 3-57, 7-57 deleting 3-58, 7-91 guidelines for naming 7-58 limitations 3-58, 7-16, 7-57 modifying the database through 3-59 querying the database through 3-58

rules for owner naming 3-7 virtual column 3-59, 7-58 with duplicate rows 3-60

W
WAIT keyword, SET LOCK MODE statement 3-50, 7-197 WARNING keyword, WHENEVER statement 2-22, 3-64, 7-213 Warning messages 1-33, 7-7, 7-213 WEEKDAY function 2-53, 7-256 WHEN keyword, CASE statement 7-21 WHENEVER statement ERROR keyword 2-22 guidelines for using 2-22 scope of reference 2-22, 7-214 syntax and notes 7-213 trapping errors 2-22, E-29 trapping warnings and NOT FOUND 2-22 WARNING keyword 2-22, 7-213 WHERE clause aggregate functions 5-47, 7-248 ALL 7-237 AND 7-234 ANY 7-237 BETWEEN 3-65, 7-229 comparison condition 7-228 ESCAPE 7-231, 7-233 EXISTS 7-238 IN 7-230, 7-238 IS NULL 7-234 joining columns in 7-234, G-1 LIKE 7-231 MATCHES 7-8, 7-232 NOT 7-218 NULL values 3-55, 7-234 OR 7-234 pattern matching in 7-34, 7-232 ranges in 7-34, 7-229 relational operators in 2-13, 7-229 search conditions 7-34, 7-218, 7-228 sets in 4-58, 7-230 SOME 7-237 syntax and notes 7-228

with a subquery 7-222, 7-237 with COLOR attribute 4-25, 4-63, E-41 with DELETE 7-73 with SELECT 7-228 with UPDATE 7-206 WHERE CURRENT OF keywords DELETE statement 3-18, 7-73 UPDATE statement 3-19, 7-207 WHILE statement 2-19 CONTINUE WHILE 7-38 EXIT WHILE 7-96 syntax and notes 7-216 WHITE attribute 4-26, 4-59, 7-77, I-19 Wildcard character 7-34, 7-232 Window attributes 7-161 automatic sizing 7-161 border 7-162, I-6, I-24 changing the current window 7-60 clearing of text 7-23 clearing the background screen 7-23 closing 7-30 color 7-163, 7-168 current 7-60, 7-161 dimensions 7-161 displaying a form 7-161 displaying a menu 7-150 locating on screen 7-161 multiple windows 7-60 opening 7-160 reserved lines in 7-161, 7-165 stack 7-30, 7-61, 7-164 WINDOW keyword CLEAR statement 7-23 CURRENT WINDOW statement 7-60 OPEN WINDOW statement 7-160 OPTIONS statement 7-168 WITH CHECK OPTION clause CREATE VIEW statement 3-60, 7-57 WITH FORM clause, OPEN WINDOW statement 7-161

Index 25

WITH GRANT OPTION keywords GRANT statement 3-60, 7-116 WITH HOLD keywords DECLARE statement 3-14, 3-20, 7-64 WITH keyword CREATE DATABASE statement 3-43 CREATE TABLE statement 7-50 CREATE VIEW statement 3-60, 7-57 DECLARE statement 3-14, 7-64 GRANT statement 3-60, 7-116 OPEN WINDOW statement 7-160 START DATABASE statement 3-43 WITH LOG IN keywords CREATE DATABASE statement 7-41 START DATABASE statement 7-200 WITH NO LOG keywords CREATE TABLE statement 7-50 SELECT statement 7-245 WITHOUT DEFAULTS keywords INPUT ARRAY statement 4-29, 6-20, 7-129 INPUT statement 4-29, 7-122 WITHOUT NULL INPUT keywords DATABASE section 4-29 WITHOUT WAITING keywords RUN statement 7-191 WORDWRAP attribute 4-21, 4-47 WORDWRAP function in a PRINT statement 5-40 syntax and notes 5-51 WORK keyword BEGIN WORK statement 3-42, 7-18 COMMIT WORK statement 3-42 ROLLBACK WORK statement 3-42 WRAP keyword, OPTIONS statement 7-166

X
X symbol in PICTURE format strings 4-38 xmc1 terminal specification 7-77, 7-127, 7-136, 7-176, I-21 XOFF key 7-125

Y
Y symbol formatting DATE values 2-46, C-3 option of bcheck utility E-3 values in syscolatt table 4-58, E-40 YEAR keyword DATETIME qualifier 2-9, 3-10, 4-20, E-12, J-2, J-5 INTERVAL qualifier 2-9, 3-10 with CURRENT function 2-31, 2-36, 7-259 with EXTEND function 2-36, 7-260 with UNITS keyword 2-43, J-15 YEAR( ) function 2-54, 7-9, 7-257 YELLOW attribute 4-26, 4-59, 7-77, I-19 YES keyword in syscolval table 4-57, E-39

Z
ZA function (termcap file) I-9, I-17 Zero default INTERVAL value 4-7, J-9 default number value 4-19 for Boolean FALSE 2-14 inserting SERIAL values 7-139 value of status variable 2-22, 7-213 zero fill ( & ) character in output fields 2-46 Zero or more characters, symbol for 7-34, 7-231, 7-232 ZEROFILL attribute of PERFORM 4-63

26

Index