0% found this document useful (0 votes)

264 views

4gl Reference Manual

Manual Informix 4GL

Uploaded by

dzapatam

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

264 views

4gl Reference Manual

Manual Informix 4GL

Uploaded by

dzapatam

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 962

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 INFORMIX’S
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 means—graphic, electronic, or mechanical, including photocopying,
recording, taping, or information storage and retrieval systems—without 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 Intro-4
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 Compiling 4GL Source Files

Chapter Overview 1-5
The Two Implementations of INFORMIX-4GL 1-5
INFORMIX-4GL (C Compiler Version) 1-7
The Programmer´s 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 Programmer’s 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 Programmer´s 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 Programmer’s Environment 1-54
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 Identifiers 2-4
Scope of Identifiers 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 2-15
INFORMIX-4GL Statements 2-16
Variable Definition 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

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 Identifiers 3-6
Owner Naming 3-7
Database Data Types 3-8
SQL Statement Summary 3-10
Data Definition 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 3-47
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

Table of Contents v
The NULL in ORDER BY Clauses 3-56
The NULL in GROUP BY Clauses 3-56
The NULL Keyword in INSERT and UPDATE Statements 3-57
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 Specification 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 Programmer’s Environment 4-62
Through the Operating System 4-63
Using PERFORM Forms in INFORMIX-4GL 4-64

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 5-44
Aggregates 5-46
LINENO 5-48
PAGENO 5-49
SPACES 5-50
WORDWRAP 5-51

Chapter 6 4GL Function Library

Chapter Overview 6-3
The 4GL Library Functions 6-3
ARG_VAL 6-4
ARR_COUNT 6-6
ARR_CURR 6-7
DOWNSHIFT 6-9

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 7-7
INFORMIX-4GL Extensions to ANSI Syntax 7-7
Definition 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

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 Demonstration Database and Application

Appendix B System Catalogs

Appendix C Environment Variables

Appendix D Reserved Words

Appendix E INFORMIX-4GL Utility Programs

Appendix F DECIMAL Functions for C

Appendix G Outer Joins

Appendix H ASCII Character Set

Appendix I Modifying termcap and terminfo

Appendix J Working with DATETIME and INTERVAL Data

Error Messages

Index

Table of Contents xi
xii Table of Contents
Introduction

Introduction
About This Manual 3
Related Informix Products and Documentation 4
Database Management Systems 5
Process Architecture 5
Informix Database Engines 6
Summary of Chapters 8
Syntax Conventions 9
The Demonstration Database 11
2 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 INFOR-
MIX-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 files into p-code
(pseudo-code) to reduce application development time.
Chapter 1 identifies the differences between these two implementations,
which mostly involve details of processing INFORMIX-4GL source files.
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 definitions 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 3
Related Informix Products and Documentation

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 definition 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 definition and manipulation languages,
because the user must define 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 instruc-
tions 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 applica-
tions contain the language statements that the database engine executes.
Informix products use a database definition 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 fol-
lowing figure shows this implementation for products on INFORMIX-SE.
MULTIPLE PROCESSES
Pipes
INFORMIX-4GL Fi
Acc le
INFORMIX-SE ess

INFORMIX-SQL INFORMIX-SE

Data
INFORMIX-SE

INFORMIX-ESQL
In Host Language C-ISAM

Introduction 5
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 INFOR-
MIX-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 specific
application, rather than queuing requests from all applications that need ser-
vice. 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 files. INFORMIX-SE works
automatically and transparently, and it does not require any special instruc-
tions 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

6 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 efficiency. 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 files 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 INFOR-
MIX-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 Programmer’s Manual for information about program-
ming issues. Notes are placed at appropriate locations in this manual to help
clarify where INFORMIX-OnLine can provide additional functionality.

Introduction 7
Summary of Chapters

Summary of Chapters
The INFORMIX-4GL Reference Manual is divided into the following chapters
and appendices:
Introduction briefly describes the INFORMIX-4GL documentation,
notational conventions used in syntax statements, and
the demonstration database.
Chapter 1 describes the C Compiler and Rapid Development System
implementations of INFORMIX-4GL. It also explains how to
create executable versions of 4GL source files, both from the
Programmer’s Environment and at the command line.
Chapter 2 gives the rules for programming in INFORMIX-4GL. It
defines data types and binding of program variables,
describes expressions and functions, and explains error
handling and the interrelationships among all the INFOR-
MIX-4GL statements.
Chapter 3 describes how to interact with databases by using the Infor-
mix extension to IBM’s Structured Query Language (SQL).
This chapter also explains the interrelationships among var-
ious types of SQL statements and illustrates the use of the
4GL Programmer’s Environment.
Chapter 4 describes the procedures to construct and compile 4GL
screen form specifications.
Chapter 5 describes the procedures to specify and produce 4GL
reports.
Chapter 6 describes the functions in the INFORMIX-4GL library.

8 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.
Appendix A describes the stores demonstration database.
Appendix B describes the system catalog tables that form the data
dictionary of an INFORMIX-4GL database.
Appendix C describes the environment variables that are used by INFOR-
MIX-4GL.
Appendix D lists the reserved words of INFORMIX-4GL.
Appendix E describes the bcheck, dbload, dbexport, dbimport,
dbschema, dbupdate, mkmessage, sqlconv, and upscol
utility programs.
Appendix F contains descriptions of C functions that handle DECIMAL
type variables in C programs.
Appendix G amplifies the Chapter 3 discussion of outer joins.
Appendix H lists the ASCII characters in order.
Appendix I describes modifications that you can make to your termcap
and terminfo files to extend function key definitions, to
specify characters for window borders, and to enable
INFORMIX-4GL programs to interact with terminals that
support color displays.
Appendix J describes how you can use the DATETIME and INTERVAL
data types.
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 9
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 state-
ment, 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 exam-
ple,
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 can-
not 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 indefinitely. 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 begin-
ning of a syntax description in Chapter 7. This means that additional options
or features are supported by INFORMIX-4GL on the INFORMIX-OnLine data-
base engine. Refer to the INFORMIX-OnLine Programmer’s 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 firm that maintains a stock
of equipment and fills 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 dem-
onstration database.
The stores database contains six tables:
customer contains information about the retail stores that purchase
sporting supplies.
orders contains information about the individual orders from the
retail stores.
items contains information about the items in an order.
stock contains information about the variety of sporting goods
available.

Introduction 11
The Demonstration Database

manufact contains information about manufacturers of sporting

goods.
state 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 5
INFORMIX-4GL (C Compiler Version) 7
The Programmer´s Environment (C Compiler Version) 7
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 Programmer’s 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) 35
INFORMIX-4GL (Rapid Development System) 36
The RDS Programmer´s 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 Undefine Option 53
The Exit Option 53
The QUERY LANGUAGE Menu 54

1-2 Compiling 4GL Source Files

Creating Executable RDS Programs 54
Working in the RDS Programmer’s 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 65
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

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 INFOR-
MIX-4GL Programmer’s 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 first create an ASCII file
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 files of INFORMIX-4GL statements into
an executable 4GL program.
Informix Software, Inc., offers two different implementations of the INFOR-
MIX-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 file.
• 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 Programmer’s Environments. Because they use different methods
to compile your 4GL source files 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 Programmer’s Environment
c4gl sfile.4gl fglpc sfile Compile 4GL source file sfile.4gl
xfile.4ge fglgo xfile Execute compiled 4GL program xfile
i4gldemo r4gldemo Create the demonstration database
The INFORMIX-4GL C Compiler Version requires no equivalent to the
fglgo command, since its compiled object files are executable without a
runner. The INFORMIX-4GL Rapid Development System also contains a
command-file 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 Programmer’s Environment
The Programmer’s 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 Undefine 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 RDS Significance of Extension
.o .4go Compiled 4GL source-code module
.4ge .4gi Executable (runable) 4GL program file
The backup file 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 files that are not interchangeable between the two 4GL imple-
mentations, however, because object code produced by a C compiler is
different from p-code.
Other filename extensions that are the same in both the C Compiler Ver-
sion and Rapid Development System Version designate interchangeable
files, 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 INFOR-
MIX-4GL. For each implementation, this chapter presents the following infor-
mation:
• It identifies and illustrates all the menu options and screen form fields
of the Programmer’s Environment.
• It describes the steps for compiling and executing INFORMIX-4GL
programs from the Programmer’s Environment.
• It describes the equivalent command-line syntax for compiling and
executing INFORMIX-4GL programs.
• It identifies the filename extensions of 4GL source-code, object, error,
and backup files.
The INFORMIX-4GL C Compiler Version is described first. If you have the
INFORMIX-4GL Rapid Development System, skip ahead to the section enti-
tled “The RDS Programmer´s Environment” near the middle of this chapter.

The Programmer´s Environment (C Compiler Version)

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

Compiling 4GL Source Files 1-7

The INFORMIX-4GL Menu

The i4gl command briefly 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
Programmer’s Environment. You have five options:
Module Work on an INFORMIX-4GL program module.
Form Work on a screen form.
Program Specify components of a multi-module program.
Query-language Use the SQL interactive interface, if you have INFOR-
MIX-SQL installed on your system.
Exit Return to the operating system.
The first 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 first 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

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 Run Exit

Change an existing 4GL program module.

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

The MODULE Design Menu supports the following options:

Modify Change an existing 4GL source-code module.
New Create a new 4GL source-code module.
Compile Compile a 4GL source-code module.
Program_Compile Compile a 4GL application program.
Run Execute a compiled 4GL program module or a multi-
module application program.
Exit Return to the INFORMIX-4GL Menu.
As in all of the menus of the Programmer’s Environment except the INFOR-
MIX-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-defined 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 file
to be modified 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

Programmer’s Environment, INFORMIX-4GL invokes that editor. The 4GL
source file whose filename you specified is the current file.
When you leave the editor, INFORMIX-4GL displays the MODIFY MODULE
Menu, with the Compile option highlighted:

MODIFY MODULE: Compile Save-and-exit Discard-and-exit

Compile the 4GL module specification.

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

If you press RETURN or type c or C to select the Compile option, INFOR-

MIX-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 file with the .o extension but makes no
attempt to link the file with other files.
The Runable option creates a compiled file with the .4ge extension. INFOR-
MIX-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 file 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.
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 file 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 file without reading the
warnings.
Alternatively, you can examine the warning messages by selecting Correct at
the next menu. When you finish editing the .err file that contains the warn-
ings, you must select Compile again from the MODIFY MODULE Menu, since
the Correct option deletes the executable file.
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
file, 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 file with extension .4gl, and create an object file with
the same filename, but with the extension .o. If you specified Runable when
you compiled, the executable version is saved with the extension .4ge. The
Discard-and-Exit option discards any changes to your file 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 Run Exit

Create a new 4GL program module.

-------------------------------------------------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 first selecting the Modify option.

MODULE: Modify New Compile Program_Compile Run Exit

Compile an existing 4GL program module.

-------------------------------------------------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 specification database, taking into account the time when the
modules were last updated.
This option is useful when you have just modified a single module of a com-
plex 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 pro-
grams, with the highlight on the module corresponding to the current file, if
any has been specified. Compiled programs must have the extension .4ge to
be included in the list. If you compile a program outside the Programmer’s
Environment and you want it to appear in the program list, give it the exten-
sion .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 Run Exit

Returns to the INFORMIX-4GL Menu.

-------------------------------------------------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 specifica-
tions. These define visual displays that 4GL applications can use to query and
modify the information in a database. INFORMIX-4GL form specification files
are ASCII files 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 Change an existing 4GL screen form specification.
Generate Create a default 4GL screen form specification.
New Create a new 4GL screen form specification.
Compile Compile an existing 4GL screen form specification.
Exit 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 specification file. 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
specification file to modify. Source files created at the FORM Design Menu
have the file extension .per. (If you use a text editor outside of the Program-
mer’s Environment to create form specification files, 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 specification source-code file that you
specified as the current file. 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 specification file.

MODIFY FORM: Compile Save-and-exit Discard-and-exit

Compile the form specification.

-------------------------------------------------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 cor-
rected 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 modified form specification file and the compiled form, or to discard
the changes. (Discarding the changes restores the version of your form
specifications 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 data-
base, to choose a filename for the form specification, and to identify the tables
that the form will access. After you provide these data, INFORMIX-4GL cre-
ates and compiles a form specification file. (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 specification.

FORM: Modify Generate New Compile Exit

Create a new form specification.

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

After prompting you for the name of your form specification file, INFOR-
MIX-4GL places you in the editor where you can create a form specification
file. 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 specification
file 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 specification file 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 Exit

Returns to the INFORMIX-4GL Menu.

-------------------------------------------------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 specifi-
cation database, called syspgm4gl. This database describes the component
modules and function libraries of your 4GL program.
If INFORMIX-4GL cannot find 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 spec-
ification, to compile and link a program, or to execute a program.
The PROGRAM Design Menu supports the following options:
Modify Change an existing program specification.
New Create a new program specification.
Compile Compile an existing program.
Planned_Compile List the steps necessary to compile and link an existing
program.
Run Execute an existing program.
Drop Delete an existing program specification.
Exit Return to the INFORMIX-4GL Menu.
You must first 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 link all the modules as an executable command file.

The Modify Option

Compiling 4GL Source Files 1-19

The PROGRAM Design Menu

the name of the program specification to be modified. It then displays a menu

and form that you can use to update the information in the program specifi-
cation database as shown in Figure 1-1:

MODIFY PROGRAM: 4GL Other Libraries Compile_Options Rename Exit

Edit the 4GL sources list.

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

Program
[myprog ]

4gl Source 4gl Source Path

[main ] [/u/john/appl/4GL ]
[funct ] [/u/john/appl/4GL ]
[rept ] [/u/john/appl/4GL ]
[ ] [ ]
[ ] [ ]

Other Source Ext Other Source Path

[cfunc ] [c ] [/u/john/appl/C ]
[ ] [ ] [ ]
[ ] [ ] [ ]
[ ] [ ] [ ]

Libraries [m ] Compile Options [ ]

[ ] [ ]

Figure 1-1 Example of a Program Specification Entry

The name of the program appears in the Program field. 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 files
and libraries. (Compiling and linking occurs when you select the Compile
option, as described later in this chapter.) In this example, the resulting exe-
cutable program would have the name myprog.4ge.
Use the 4GL option to update the entries for the 4GL Source fields and the 4GL
Source Path fields on the form. The five rows of fields 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
redefine 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 filename and location of each non-INFORMIX-4GL
source-code or object-code module in these fields. Enter the name of the
module in the Other Source field, the filename extension of the module (for
example, ec for an INFORMIX-ESQL/C module, or c for a C module) in the
Ext field, and the full directory path of the module in the Other Source Path
field. The example in Figure 1-1 includes a file containing C function source-
code (cfunc.c) located in /u/john/appl/C. You can list up to 100 files 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 prefix, so you should enter only
what follows the prefix. 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 field. You cannot, however,
specify the -e or -a options of c4gl in this field. (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 specifi-
cation of the program modules and libraries that make up an application pro-
gram. 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 first 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 specification database, taking into account the time when each file
was last updated. It compiles only those files that have not been compiled
since they were changed.

PROGRAM: Modify New Compile Planned_Compile Run Drop Exit

Compile a 4GL application program.

-------------------------------------------------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 files 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
(files with the extension .4ge) and positions the highlight on the current
program, if a program has been specified. INFORMIX-4GL then executes the
program that you select.

PROGRAM: Modify New Compile Planned_Compile Run Drop Exit

Execute a 4GL application program

-------------------------------------------------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 definition of that program
from the syspgm4gl database. This action removes the definition 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 INFOR-
MIX-4GL Menu.

1-24 Compiling 4GL Source Files

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 Programmer’s Environ-
ment. 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 file.
4. Link the object file with the INFORMIX-ESQL/C libraries, and to any addi-
tional libraries whose functions are called.
The sections that follow describe how to carry out these steps, both from the
Programmer’s Environment and at the system prompt.

Working in the Programmer’s 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 Programmer’s Environment. After
a pause for the sign-on message, the INFORMIX-4GL Menu appears.

Compiling 4GL Source Files 1-25

Working in the Programmer’s 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 modified, 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 files in the same directory, and among the other program mod-
ules, if it will be part of a multi-module program. INFORMIX-4GL attaches
extension .4gl to this identifier, as the filename of your new source
module.

Revising an Existing Module

If you are revising an existing 4GL source file, 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 file to edit. Use the Arrow
keys to highlight the name of a source module and press RETURN, or
enter a filename (with no extension).
If you specified 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 finished entering or editing your 4GL code, use an
appropriate editor command to save your source file and end the text
editing session.

1-26 Compiling 4GL Source Files

Working in the Programmer’s Environment

Compiling a Source Module

The .4gl source file module that you create or modify is an ASCII file that must
be compiled before it can be executed. After you save your file 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 first creates an intermediate ESQL/C version
of your source-code module, then calls the ESQL/C preprocessor which
produces C output, and finally calls the C compiler to produce a compiled
file with the same filename, 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 file module, with the same
filename, but with extension .o. See also the procedures for linking pro-
gram modules, which are described later in this section.
If the compiler detects errors after either option, no compiled file is cre-
ated, and the screen prompts you to select Correct or Exit. Follow the first
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 file.
• Edit the file to correct the error, and select Compile again. If an error mes-
sage 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 file and
compile it with the mkmessage utility. See Chapter 8 of the INFORMIX-

Compiling 4GL Source Files 1-27

Working in the Programmer’s Environment

4GL User Guide for more information about help messages in INFOR-
MIX-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 modified module is part of a multi-module 4GL program,
however, you must link all of the modules into a single program file 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 file 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 first field.
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 Programmer’s Environment

MODIFY PROGRAM: 4GL Other Libraries Compile_Options Rename Exit

Edit the 4GL sources list.
-------------------------------------------------Press CTRL-W for Help------
Program
[ ]
4gl Source 4gl Source Path
[ ] [ ]
[ ] [ ]
[ ] [ ]
[ ] [ ]
[ ] [ ]
Other Source Ext Other Source Path
[ ] [ ] [ ]
[ ] [ ] [ ]
[ ] [ ] [ ]
[ ] [ ] [ ]
Libraries [ ] 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 file extension. Repeat this step for every module.
If the module is not in the current directory nor in a directory specified 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 files, you
should select the Other option. This option enables you to specify each
filename in the Other Source field, the filename extension in the Ext field,
and the pathname in the Other Source Path field.
These fields are part of an array that can specify up to 100 ‘‘other’’ mod-
ules, such as C language source files or object files. If you have the INFOR-
MIX-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 fields.
• Select the Compile_Options option if you want to specify compiler flags.
These flags can be entered or edited in the Compile Options fields.
• 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 file that contains all your 4GL program modules.
Its filename is the program name that you specified, 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 files that are pro-
duced automatically when you work at the Programmer’s 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, win-
dows, or other screen output according to your program logic and your key-
board interaction with the program.

Working at the Command Line

You can also create .4gl source files and compiled .o and .4ge files at the oper-
ating 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 .o
Source .c, .ec Object
Files Files Files

.err .4ge
PREPROCESSOR
Error Compiled
& COMPILER
File Program
c4gl
File

Figure 1-2 Creating and Running an INFORMIX-4GL Program

1-30 Compiling 4GL Source Files

Working at the Command Line

Here the rectangles represent processes controlled by specific commands,

and the circles represent files. Arrows indicate whether a file can serve as
input or output (or as both) for a process.
This diagram is simplified 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 files (.4gl),
INFORMIX-ESQL/C source files (.ec), C language source files (.c), and
object files (.o).
• The program module can then be compiled, by invoking the c4gl prepro-
cessor and compiler command. (If error messages result, find them in the
.err file and edit the source file to correct the errors. Then recompile the
corrected source module.)
The resulting compiled .4ge program file is an executable command file
that you can run by entering its name at the system prompt:
filename.4ge
where filename.4ge specifies your compiled 4GL file.
The correspondence between commands and menu options of the Program-
mer’s Environment is summarized by the following list:
Command Invokes Menu Option
vi UNIX System Editor Module New/Modify
c4gl 4GL Preprocessor/Compiler Compile
filename.4ge 4GL Application Run

Creating or Modifying a 4GL Source File

Use your system editor or another text editing program to create a .4gl source
file or to modify an existing file. 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 file at the system prompt by
entering a command of the form:
c4gl source.4gl -o filename.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 filename.4ge. The com-
plete 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 ref-
erence. 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 files (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 file.
4. Links the object file to the INFORMIX-ESQL/C libraries and to any addi-
tional libraries that you specify in the command line.
You must assign the filename extension .4gl to any INFORMIX-4GL source-
code modules that you compile. The resulting .4ge file is an executable ver-
sion of your program.
Notice that ESQL/C source files (with extension .ec), C source files (with
extension .c), and C object files (with extension .o) are intermediate steps in
producing an executable INFORMIX-4GL program. Besides 4GL source files
(with extension .4gl), you can also include files 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 outfile ] source.4gl . . .
[ otheresql.ec . . . ] [ othersrc.c . . . ] [ otherobj.o . . . ] [ yourlib . . . ] }

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

1-32 Compiling 4GL Source Files

Working at the Command Line

-e performs only the preprocessor steps, with no compilation

or linking.
-a causes your compiled program to check array bounds at run
time. The -a option must appear on the command line before
the source.4gl filename.
-otherargs are other arguments for your C compiler.
outfile is a name that you assign to the compiled 4GL program.
source.4gl is the name of an INFORMIX-4GL source module. You must
specify the .4gl extension.
otheresql.ec is an ESQL/C source file to compile and link.
othersrc.c is a C language source file to compile and link.
otherobj.o is an object file to link with your 4GL program.
yourlib is a library from which to extract functions that are not part
of the INFORMIX-4GL or INFORMIX-ESQL/C libraries.

Notes
1. If you specify the -V option to display the version number, all other
arguments are ignored, and no output files 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 files (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 first 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.) Com-
piler warnings and error messages are saved in a file called source.err.
6. If you omit the -o outfile option, the default filename 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 files mod1.o, mod2.o, and mod3.o are previ-
ously 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
file (or whatever you specify after the -o argument) that is an executable
command file.
To execute your compiled INFORMIX-4GL application program, enter the
filename 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 filenames, depending on the logic of your
specific 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-defined 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)

Source, runable, error, and backup files generated by INFORMIX-4GL are
stored in the current directory and are labeled with a filename extension. The
following list shows the file extensions for the source, runable, and error files.
These files are produced during the normal course of using the C Compiler
Version of INFORMIX-4GL.

file.4gl is an INFORMIX-4GL source file.

file.o is an INFORMIX-4GL object file.
file.4ge is an INFORMIX-4GL executable (runable) file.
file.err is an INFORMIX-4GL source error file, created when an
attempt to compile a module fails. The file contains INFOR-
MIX-4GL source code, plus any compiler syntax error or
warning messages.
file.ec is an intermediate source file, created during the normal
course of compiling an INFORMIX-4GL module.
file.c is an intermediate C file, created during the normal course of
compiling an INFORMIX-4GL module.
file.erc is an INFORMIX-4GL object error file, created when an
attempt to compile or to link a non-INFORMIX-4GL source-
code or object module fails. The file contains INFORMIX-4GL
source code and annotated compiler errors.
form.per is a FORM4GL source file.
form.frm is a FORM4GL object file.
form.err is a FORM4GL source error file.
The last three files do not exist unless you create or modify a screen form
specification file, as described in Chapter 4.
The next page lists the corresponding file extensions for the backup files
that INFORMIX-4GL automatically creates when you use the Programmer’s
Environment to process 4GL source files.
The following list identifies the backup files that are produced when you use
INFORMIX-4GL from the Programmer’s Environment.

file.4bl is an INFORMIX-4GL source backup file, created during the

modification and compilation of a .4gl program module.
file.4bo is an object backup file, created during the compilation of
a .o program module.

Compiling 4GL Source Files 1-35

INFORMIX-4GL (Rapid Development System)

file.4be is an object backup file, created during the compilation

of a .4ge program module.
file.pbr is a FORM4GL source backup file.
file.fbm is a FORM4GL object backup file.
Under normal conditions, INFORMIX-4GL creates the backup files and
intermediate files as necessary and deletes them upon a successful compila-
tion. If you interrupt a compilation, you may find one or more of these files
in your current directory.
During the compilation process, INFORMIX-4GL stores a backup copy of the
file.4gl source file in file.4bl. The time stamp is modified on the (original)
file.4gl source file, but not on the backup file.4bl file. In the event of a system
crash, you may need to replace the modified file.4gl file with the backup copy
contained in the file.4bl file.
The Programmer’s Environment does not allow you to begin modifying a
.4gl or .per source file if the corresponding backup file already exists in the
same directory. After an editing session terminates abnormally, for example,
you must delete or rename any backup file before you can resume editing
your 4GL module or form from the Programmer’s 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 implementa-
tions of INFORMIX-4GL.

The RDS Programmer´s Environment

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

1-36 Compiling 4GL Source Files

The INFORMIX-4GL Menu

The r4gl command briefly 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------

Compiling 4GL Source Files 1-37

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 file.

MODULE: Modify New Compile Program_Compile Run Debug Exit

Change an existing 4GL program module.

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

The MODULE Design Menu supports the following options:

Modify Change an existing 4GL source-code module.
New Create a new 4GL source-code module.
Compile Compile an existing 4GL source-code module.
Program_Compile Compile a 4GL application program.
Run Execute a compiled 4GL module or multi-module
application program.
Debug 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).
Exit Return to the INFORMIX-4GL Menu.
As in all of the menus of the Programmer’s Environment except the INFOR-
MIX-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-defined 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 file to be modified, 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
Programmer’s Environment, INFORMIX-4GL invokes that editor. The 4GL
source file whose filename you specified is the current file.
When you leave the editor, INFORMIX-4GL displays the MODIFY MODULE
Menu, with the Compile option highlighted:

MODIFY MODULE: Compile Save-and-exit Discard-and-exit

Compile the 4GL module specification.

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

If you press RETURN or type c or C to select the Compile option, INFOR-

MIX-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 file with a .4go extension. The Runable option
creates a file 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 file 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 file 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 file without reading the warnings.
Alternatively, you can examine the warning messages by selecting Correct
at the next menu. When you finish editing the .err file that contains the
warnings, you must select Compile again from the MODIFY MODULE Menu,
since the Correct option deletes the p-code file.
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
file, 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, INFOR-
MIX-4GL saves the current source-code module as a disk file with the file-
name extension .4gl, and saves the compiled version as a file with the same
filename, but with the extension .4go or .4gi. If you select the Dis-
card-and-Exit option, INFORMIX-4GL discards any changes made to
your file 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 Run Debug Exit

Create a new 4GL program module.

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

The Compile Option

The Compile option enables you to compile an individual 4GL source-code
module without first selecting the Modify option.

MODULE: Modify New Compile Program_Compile Run Debug Exit

Compile an existing 4GL program module.

-------------------------------------------------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 specification database, taking into account the time when the mod-
ules were last updated. This option is useful when you have just modified 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 file,
if any has been specified. 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 filename and extension at the prompt. If no com-
piled 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 Run Debug Exit

Returns to the INFORMIX-4GL Menu.

-------------------------------------------------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 Run Debug Exit

Returns to the INFORMIX-4GL Menu.

-------------------------------------------------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 specifica-
tions. These specifications define visual displays that 4GL applications can
use to query and modify the information in a database. INFORMIX-4GL
screen form specifications are ASCII files 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 Change an existing 4GL screen form specification.
Generate Create a default 4GL screen form specification.

Compiling 4GL Source Files 1-43

The FORM Design Menu

New Create a new 4GL screen form specification.

Compile Compile an existing 4GL screen form specification.
Exit 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
specifications.

The Modify Option

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
specification file to modify. Source files created at the FORM Design Menu
(or at the command line by the FORM4GL screen form facility) have the file
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 specification source-code file that you
specified as the current file. When you leave the editor, INFORMIX-4GL
displays the MODIFY FORM Menu with the Compile option highlighted.

MODIFY FORM: Compile Save-and-exit Discard-and-exit

Compile the form specification.

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

Now you can press RETURN to compile the revised form specification file.
If the compiler finds 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 modified form specification file and the compiled form, or to discard
the changes. (Discarding the changes restores the version of your form
specifications 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 data-
base, to choose a filename for the form specification, and to identify the tables
that the form will access. After you provide this information, INFORMIX-4GL
creates and compiles a form specification file. (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 specification.

FORM: Modify Generate New Compile Exit

Create a new form specification.

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

1-46 Compiling 4GL Source Files

The FORM Design Menu

The Compile Option

The Compile option enables you to compile an existing form specification
file 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 specification file and
then performs the compilation. If the compilation is not successful, INFOR-
MIX-4GL displays the COMPILE FORM Menu with the highlight on the Cor-
rect option.

The Exit Option

The Exit option clears the FORM Design Menu from the screen.

FORM: Modify Generate New Compile Exit

Returns to the INFORMIX-4GL Menu.

-------------------------------------------------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

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 specification data-
base, called syspgm4gl. This database describes the runner options and the
modules of your program.
If INFORMIX-4GL cannot find 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 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
specification, to compile a program, or to execute or analyze a program.
The PROGRAM Design Menu supports the following eight options:
Modify Change an existing program specification.
New Create a new program specification.
Compile Compile an existing program.
Planned_Compile Display the steps to compile an existing program.
Run Execute an existing program.
Debug Invoke the INFORMIX-4GL Interactive Debugger.
Undefine Delete an existing program specification.
Exit Return to the INFORMIX-4GL Menu.

1-48 Compiling 4GL Source Files

The PROGRAM Design Menu

You must first 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 specification of an existing
4GL program. (This option is not valid unless at least one program has
already been specified. If none has, you can create a program specification
by selecting the New option from the same menu.) INFORMIX-4GL prompts
you for the name of the program specification you want to modify. It then
displays a screen and menu that you can use to update the information in the
program specification database, as shown in Figure 1-3:

MODIFY PROGRAM: 4GL Globals Other Program_Runner Rename Exit

Edit the 4GL sources list.

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

Program [myprog ]
Runner [fglgo ] Runner Path [ ]
Debugger [fgldb ] Debugger Path [ ]

4gl Source 4gl Source Path

[main ] [/u/john/appl/4GL ]
[funct ] [/u/john/appl/4GL ]
[rept ] [/u/john/appl/4GL ]
[ ] [ ]
[ ] [ ]

Global Source Global Source Path

[ ] [ ]
[ ] [ ]

Other .4go Other .4go Path

[obj ] [ ]
[ ] [ ]

Figure 1-3 Example of a Program Specification Entry

The name of the program appears in the Program field. 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 files. (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 five rows of fields 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 rede-
fine 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 contain-
ing REPORT statements (rept.4gl). These modules are all located in the direc-
tory /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 modification of the glo-
bals module file 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 fields. This is where you specify the name and location of
other 4GL object files (.4go files) to include in your program. Do not specify
the filename extensions. You can list up to 100 files 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 cus-
tomized 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 field, 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 fields 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 Func-
tions” 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
specification of the program modules and libraries that make up the desired
application program.

PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit

Add the compilation definition of a 4GL application program.

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

The New option is identical to the Modify option, except that you must first
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 specification database, taking into account the time when files were
last updated. INFORMIX-4GL compiles only those files that have been modi-
fied since they were last compiled, except in the case where you have modi-
fied a module listed in the Global Source array. If you have modified a module
that is listed in the Global Source array, all files are recompiled.

PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit

Compile a 4GL application program.

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

The Compile option produces a runable p-code file 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 files in the depen-
dency 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 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
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 Undefine Exit

Execute a 4GL application program

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

The screen lists any compiled programs (files with the extension .4gi)
and highlights the current program, if one has been specified. This option
resembles the Run option of the MODULE Design Menu.
Although .4go files are not displayed, you can also enter the name and
extension of a .4go file. Whatever compiled program you select is executed
by fglgo, or by the runner that you specified in the Runner field of the
Program Specification 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 Exit

Drop the compilation definition of a 4GL application program.

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

The Undefine Option

The Undefine option of the PROGRAM Design Menu prompts you for a
program name and removes the compilation definition of that program from
the syspgm4gl database. This action removes the definition only. Your
program and 4GL modules are not removed.

PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine 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 from the screen and
restores the INFORMIX-4GL Menu.

Compiling 4GL Source Files 1-53

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 pur-
chased 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 Programmer’s Environ-
ment. 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 file.

2. Compile the source file into a .4go p-code file.
3. Combine multiple .4go modules into a single .4gi file.
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 Programmer’s 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 applica-
tions that do not call programmer-defined C functions.)

Working in the RDS Programmer’s 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
Programmer’s Environment. After a sign-on message, the INFORMIX-4GL
Menu appears.

1-54 Compiling 4GL Source Files

Working in the RDS Programmer’s 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 modified, skip ahead to the next sec-
tion, ‘‘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 files in the same directory, and among the other program mod-
ules, if it will be part of a multi-module program. INFORMIX-4GL attaches
extension .4gl to this identifier, as the filename of your new source
module.

Revising an Existing Module

If you are revising an existing 4GL source file, 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 file to edit. Use the Arrow
keys to highlight the name of a source module and press RETURN, or
enter a filename (with no extension).
If you specified 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 edi-
tor. Now you can begin an editing session by entering 4GL statements.
(The chapters that follow describe INFORMIX-4GL statements and
programs.)
• When you have finished entering or editing your 4GL code, use an appro-
priate editor command to save your source file and end the text editing
session.

Compiling 4GL Source Files 1-55

Working in the RDS Programmer’s Environment

Compiling a Source Module

The .4gl source file module that you create or modify is an ASCII file that must
be compiled before it can be executed. After you save your file 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 filename, 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 filename, 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 file is
created, and the screen prompts you to select Correct or Exit. Follow the
first 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 file.
• Edit the file 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 file and
compile it with the mkmessage utility. See Chapter 8 of the INFORMIX-
4GL User Guide for more information about implementing help messages
in INFORMIX-4GL programs.

1-56 Compiling 4GL Source Files

Working in the RDS Programmer’s 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 modified module is part of a multi-module 4GL program,
however, you must combine all of the modules into a single program file
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 file 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 first field.
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 Other Program_Runner Rename Exit

Edit the 4GL sources list.

----------------------------------------------- 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 Programmer’s 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 mod-
ule, without the .4gl file extension. Repeat this step for every module. If
the module is not in the current directory or in a directory specified 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 INFOR-
MIX-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 com-
piled, you can select the Other option to enter or edit their filenames 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 file that combines all of your .4gl source files into an executable pro-
gram. Its filename is the program name that you specified, 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 files that are produced
automatically when you work at the Programmer’s 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 first 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 Programmer’s 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 programmer’s productivity tool.

Working at the RDS Command Line

You can create the same .4gl source files and compiled .4go and .4gi p-code
files 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
DEBUGGER
COMPILER
fgldb
fglpc

.4go
Compiled
p-code
File

P-CODE
RUNNER
fglgo

Figure 1-4 Creating and Running a Single-Module Program

Here the rectangles represent processes controlled by specific commands,

and the circles represent files. Arrows indicate whether a file serves as input
or output for a process.
This diagram is simplified 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, find them in
the .err file, and edit the .4gl file to correct the errors. Then recompile the
corrected .4gl file.)

1-60 Compiling 4GL Source Files

Working at the RDS Command Line

• The following command line invokes the p-code runner:

fglgo filename
where filename specifies a compiled 4GL file to be executed.
Executing a program that is undergoing development or modification some-
times 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 filename
where filename specifies your compiled 4GL file. 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
Programmer’s Environment is summarized by the following list:
Command Invokes Menu Option
vi UNIX System Editor Module New/Modify
fglpc 4GL P-Code Compiler Compile
fglgo 4GL P-Code Runner Run
fgldb 4GL Interactive Debugger Debug

Creating or Modifying a 4GL Source File

Use your system editor or another text-editing program to create a .4gl source
file, or to modify an existing file. 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 file. Do this at the system prompt by entering the fglpc
command, which compiles your 4GL source code, and generates a file con-
taining 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 INFOR-
MIX-4GL Interactive Debugger, if you have the Debugger).

The INFORMIX-4GL source-code module to be compiled should have the file

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

Notes
1. The fglpc command reads source.4gl files and creates a compiled version
of each, with the filename source.4go. You can specify any number of
source files, in any order, with or without their .4gl filename 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 with-
out compiling.
3. If you specify the -ansi option, it must appear first 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 file called source.err. Look in source.err to find where the error or warn-
ing occurred in your code.
5. You can use the -p pathname option to specify a non-default directory for
the .4go and .err files. Otherwise, any files 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 file single.4gl, and creates a
file called single.4go in the current directory:
fglpc single.4gl
The next command line compiles two 4GL source files:
fglpc -p /u/ken fileone filetwo

1-62 Compiling 4GL Source Files

Working at the RDS Command Line

This command generates two compiled files, fileone.4go and filetwo.4go,

and stores them in subdirectory /u/ken. Any compiler error messages are
saved in files fileone.err or filetwo.err in the same directory.

Concatenating Multi-Module Programs

If a program has several modules, the compiled modules must all be concat-
enated into a single file, 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 files into the file specified 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 files into a file called new.4gi.
Note: The new filename of the combined file must have either a .4go or a .4gi exten-
sion. Throughout this manual, extension .4gi designates runable files that have been
compiled (and concatenated, if several source modules comprise the program). You
may wish to follow this convention in naming files, since only .4gi files are displayed
from within the Programmer’s Environment. This convention is also a convenient
way to distinguish complete program files from object files that are individual mod-
ules 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 Func-
tions’’ 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 ] filename[.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.
-a causes array bounds checking at run time.
filename is the name of a compiled 4GL file. The filename must have
a .4go or .4gi extension. You do not need to enter this exten-
sion on the command line.
args are any arguments required by your 4GL program.

1-64 Compiling 4GL Source Files

Working at the RDS Command Line

Notes
1. If you do not specify a filename extension in the command line, fglgo
looks first for the filename with a .4gi extension, and then for the filename
with a .4go extension.
2. To run a 4GL program that calls programmer-defined 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 com-
mand 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 first 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 Interac-
tive 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 com-
mand line of the form:
fgldb filename
Here filename is any runable 4GL file that you produced by an fglpc com-
mand. 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 program-
mer-defined C functions, you must create a customized runner to execute the
program. You can do this by following two steps:
1. Edit a structure definition file to contain information about your C func-
tions. This file is named fgiusr.c and is supplied with INFORMIX-4GL.
2. Compile and link the fgiusr.c file with the files that contain your C func-
tions. 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 file 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 INFOR-
MIX-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 file named fgiusr.c. This
file 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 file 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 0’s 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 file is a C language file that you can edit to declare any number
of programmer-defined C functions.

Compiling 4GL Source Files 1-67

Working at the RDS Command Line

To edit fgiusr.c, you can copy the file to any directory. (Unless this is your
working directory at compile time, you must specify the full pathname of the
edited fgiusr.c file 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 first 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 func-
tion). If the number of arguments expected by the function can vary, make the
third argument the maximum number of arguments, prefixed 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 file:
#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 func-
tion-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-specific runners. In this case, you can
either make a copy of the fgiusr.c file (with a new name) for each custom-

1-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 specific 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 first 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 con-
tain functions declared in an edited fgiusr.c file.

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

Explanation
-V displays the version number of the software.
fgiusr.c is the name of the file that you edited to declare C and/or
INFORMIX-ESQL/C functions.
cfile is the name of a source file containing INFORMIX-ESQL/C or
C functions to be compiled and linked with the new runner;
or the name of an object file previously compiled from a .c
or .ec file.
-o newfglgo specifies the name of the customized runner.

Notes
1. The cfglgo command compiles and links the edited fgiusr.c file with
your C program files into an executable program that can run your 4GL
application.
2. You can rename an edited structure definition file. If you do so, specify its
new filename 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 INFOR-
MIX-ESQL/C files in a cfglgo command line.
5. You must have the INFORMIX-ESQL/C product to compile INFOR-
MIX-ESQL/C files with cfglgo.

Compiling 4GL Source Files 1-69

Working at the RDS Command Line

6. If the fgiusr.c file 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 defined in file 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 file:

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 file follows:
line 1: The file ‘‘fgicfunc.h’’ is always included. This line already exists
in the unedited fgiusr.c file.
line 3: This is the declaration of the function prdate( ). You must add
this line to the file.
line 4: This line already exists in the unedited file. It declares the
structure array usrcfuncs.
line 6: This line contains the initializers for function prdate( ). Since
it expects no arguments, the third value is zero.
line 7: 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 specified in the edited fgiusr.c file.
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 Programmer’s 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-defined C functions. Then you
can return to the Programmer’s 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

file.4gl is an INFORMIX-4GL source file.

file.4go is an INFORMIX-4GL file that has been compiled to p-code.
file.4gi is an INFORMIX-4GL file that has been compiled to p-code.
file.err is an INFORMIX-4GL source error file, created when an attempt to
compile a module fails or produces a warning. The file contains
the 4GL source code plus compiler syntax warnings or error
messages.
file.erc is an INFORMIX-4GL object error file, created when an attempt to
compile or to link a non-INFORMIX-4GL source-code or object
module fails. The file contains 4GL source code and annotated
compiler errors.
form.per is a FORM4GL source file.
form.frm is a FORM4GL object file.
form.err is a FORM4GL source error file.

1-72 Compiling 4GL Source Files

RDS Program Filename Extensions

The last three files do not exist unless you create or modify a screen form
specification file, as described in Chapter 4.
The next page lists the corresponding file extensions for the backup files that
INFORMIX-4GL automatically creates when you use the Programmer’s Envi-
ronment to process 4GL source files.
The following list identifies backup files that are produced when you use
INFORMIX-4GL from the Programmer’s Environment.
file.4bl is an INFORMIX-4GL source backup file, created during the mod-
ification and compilation of a .4gl program module.
file.4bo is an object backup file, created during the compilation of a .4go
program module.
file.4be is an object backup file, created during the compilation of a .4gi
program module.
file.pbr is a FORM4GL source backup file.
file.fbm is a FORM4GL object backup file.
Under normal conditions, INFORMIX-4GL creates the backup files and inter-
mediate files as necessary, and deletes them upon a successful compilation. If
you interrupt a compilation, you may find one or more of the files 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
files in the directory specified by pathname, rather than in your current
directory.
During the compilation process, INFORMIX-4GL stores a backup copy of the
file.4gl source file in file.4bl. The time stamp is modified on the (original)
file.4gl source file, but not on the backup file.4bl file. In the event of a system
crash, you may need to replace the modified file.4gl file with the backup copy
contained in the file.4bl file.
The Programmer’s Environment does not allow you to begin modifying a
.4gl or .per source file if the corresponding backup file already exists in the
same directory. After an editing session terminates abnormally, for example,
you must delete or rename any backup file before you can resume editing
your 4GL module or form from the Programmer’s Environment.
This concludes the description of the Rapid Development System. Except as
otherwise noted, the descriptions of INFORMIX-4GL elsewhere in this man-
ual 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
2
Chapter Overview 3
Language Conventions 3
Comments 3
INFORMIX-4GL Identifiers 4
Scope of Identifiers 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 13
Binding to Database and Forms 14
The THRU Keyword and the .* Notation 15
INFORMIX-4GL Statements 16
Variable Definition 17
Assignment 17
Program Organization 17
Program Flow 18
Screen Interaction 19
Report Generation 21
Error and Exception Handling 21
Error Handling 22
Exception Handling 23
Data Validation 23
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 files, each
containing a series of English-like statements that obey a well-defined syntax.
This chapter describes the syntax rules and gives an overview of those state-
ments that do not apply directly to a database. It lists the built-in 4GL func-
tions 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 identifiers, 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 neces-
sary, it uses the keyword END in association with the statement type to termi-
nate 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 files. 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 Identifiers

• You can also use a pair of hyphens or minus signs (--) to begin a com-
ment 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 Identifiers
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
identifier as a name. An identifier is a sequence of letters, digits, and under-
scores ( _ ). The first character must be a letter or an underscore. Only the first
eight characters are significant, and the case of letters is ignored. Identifiers
must not be the same as keywords (which are listed in Appendix D).
INFORMIX-4GL identifiers can be the same as SQL identifiers, but such use
requires special attention when you use the identifier in an SQL statement.
(See Chapter 3 for a discussion of SQL statements, objects, cursors, and
identifiers.)

Scope of Identifiers
Program variables can be either local, modular, or global in their scope of
reference.
• Local variables must be defined within a MAIN, FUNCTION, or REPORT
program block. They cannot be referenced by statements outside that
program block.
• Module variables must be defined before the first program block (that is,
before the MAIN statement or before any REPORT or FUNCTION state-
ment). They can be referenced only by statements in the same module.
• Global variables must be defined either prior to the MAIN statement
(and in a DEFINE statement preceded by a GLOBALS statement and fol-
lowed by an END GLOBALS statement) or in a separate globals file. Other
program files using these variables must include the statement GLOBALS
‘‘globals-filename’’ (where globals-filename contains the definitions of the
global variables).

2-4 INFORMIX-4GL Programming

Constants

Forms, cursors, functions, reports, windows, and some 4GL statements have
identifiers that are not program variables. The scope of reference for identifi-
ers of forms, windows, functions, and reports is the entire program. The
scope of the identifiers 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, floating number, and date and time constants.
INFORMIX-4GL recognizes three predefined 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 con-
stants. 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 significance 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 first 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 dou-
ble 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) qualifier
where type is the keyword DATETIME or INTERVAL, values are a list of calen-
dar date values and/or time-of-day values for DATETIME, or else date or time
values for INTERVAL; and qualifier identifies the largest and smallest units
that the values describe. The following example specifies an instant in time on
March 6th, 1989, and illustrates the delimiters that separate fields within the
values:
DATETIME (89-3-6 09:55:30.825) YEAR TO FRACTION(3)
You can prefix an INTERVAL literal with ‘‘+’’ or ‘‘-’’ to indicate a positive or
negative interval. If the qualifier is only a single field, an INTERVAL can also
be of the form:
expression UNITS field
Here expression is a number expression, and field is one of the keywords YEAR,
MONTH, DAY, HOUR, MINUTE, SECOND, or FRACTION (n). (The last desig-
nates 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 Programmer’s 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
define 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

identifier 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 MONEY [ (m [ , n ] ) ]
INTEGER CHAR [ ( n ) ]
INT CHARACTER [ (n ) ]
DECIMAL [ (m [ , n ] ) ] DATE
DEC [ ( m [ , n ] ) ]
NUMERIC [ (m [ , n ] ) ] DATETIME qualifier
SMALLFLOAT INTERVAL qualifier
REAL
RECORD [ LIKE table. * ]
FLOAT [ ( n ) ]
DOUBLE PRECISION [ ( n ) ] 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 floating-point numbers with a total of
m (≤ 32) significant 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 fixed-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 floating decimal. DECIMAL(m) variables have a precision of m,
and a range in absolute value from 10-128 to 10126 When printed without for-
matting 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 floating
decimal.
You can also use the keywords DEC or NUMERIC as synonyms for DECIMAL.

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

FLOAT [ ( n ) ]
This data type includes floating-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 param-
eters. 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
defined 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 fixed 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 char-
variable[m,n], which selects the mth through the nth components of the vari-
able 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
specifications. A DATETIME value specifies a contiguous sequence of the
fields: 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 fields. 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 fields: YEAR and MONTH, or DAY, HOUR, MINUTE, SECOND,
and FRACTION (of a second), but you can specify a non-default precision for
a field. Internal storage is the same as for DATETIME values. See also
Appendix J, “Working with DATETIME and INTERVAL Data.”

LIKE table.column
You can define 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 definition 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 limita-
tions on using record-name.*.) You can define a record by listing its elements

INFORMIX-4GL Programming 2-9

Data Conversion

and their types, or by defining it to be LIKE table.* , where table is a table in the
database. If defined 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 char-
array[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 Programmer’s 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, INFOR-
MIX-4GL converts the string or date to an appropriate number. INFOR-
MIX-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 To
FLOAT DECIMAL(16)
SMALLFLOAT DECIMAL(8)
INTEGER DECIMAL(10,0)
SMALLINT 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 sec-
tion for arithmetic operations on operands with definite scale. When one
of the operands has no scale (floating decimal), the result is a floating
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 sig-
nificant digits INFORMIX-4GL reports an error.
• Leading or trailing zeros are not considered significant 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 first operand, and p2
and s2 are the precision and scale of the second operand.
Operation Precision and Scale of Result
Addition and Precision: MIN(32, MAX(p1 - s1, p2 - s2) + MAX(s1, s2) + 1)
Subtraction Scale: MAX(s1, s2)

Multiplication Precision: MIN(32, p1+ p2)

Scale: s1 +s2

Division Precision: 32
Scale: 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 Operation
** Exponentiation

* Multiplication
/ Division
mod 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 Operation
, Concatenation
[m,n] Substring where m is the starting position
and n is the ending position
CLIPPED Drop trailing blanks
USING Formatting
WORDWRAP 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 format-
ting numbers and dates. The WORDWRAP function is used only in 4GL
reports, and is described in Chapter 5. The next page lists 4GL Boolean oper-
ators 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 “Opera-
tions 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 Operation
= Equal to
!= or <> 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 [ ESCAPE " esc-char " ]
• 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 )

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 defined them, there is no implicit relationship
between program variables, screen fields, and database columns. Even when
a variable lname is defined to be LIKE customer.lname, changes to the pro-
gram variable do not imply any change in the column value. Similarly, even
if you created screen field customer.lname using the same database column
as a model, there is no inherent connection between the program variable and
the field. 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 first 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 vari-
able name and the screen field name. (See the individual statement descrip-
tions 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

INFORMIX-4GL provides two devices to simplify the writing of 4GL state-
ments 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 vari-
ables 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 fields 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 defined. 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 definition of a screen record, THRU runs through all the fields in the
order that they are listed in the ATTRIBUTES section of the form specifica-
tion file, from the field first 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 specification file 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 defined 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 defining
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 Definition

Variable Definition
You must define all program variables before you can use them.
DEFINE associates an INFORMIX-4GL identifier with a data type.
DEFINE statements must be the first statements within a
program block (to define local variables) or must be within
a GLOBALS statement (to define global variables). Variables
defined after the GLOBALS section (if it is present) and before
MAIN, the first FUNCTION, or first 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.
INITIALIZE 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.

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 pro-
gram. 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.
FUNCTION contains a sequence of INFORMIX-4GL statements that per-
form 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

Program Flow

routine that called it. You can pass the values of variables to
functions as parameters.
REPORT contains format and output specifications for a report.
GLOBALS identifies 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 file 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 first 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 defines 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 flow 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.
FOR begins an indexed loop of statements (ended by END FOR)
that will be executed until the index reaches a programmer-
supplied value.
FOREACH 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.

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.
CONTINUE permits a premature cycling of a loop or menu.
EXIT permits a premature exit from a FOR, FOREACH, WHILE,
MENU, INPUT, or CASE statement, or from the entire
program.
IF executes one or more statements conditionally (ended by
END IF).
CASE executes a different sequence of statements (ended by END
CASE) depending upon the current value of an expression.
GOTO passes program control immediately to a designated place in
the program.
LABEL marks the place in the program where a GOTO statement can
pass control.
SLEEP causes the program to pause for a specified length of time.
RUN executes an operating system program and returns control
to the INFORMIX-4GL program.

Screen Interaction
The next 18 statements allow the program to interact with the screen. The first
statement constructs a menu; the next five statements provide control over
clearing the screen, printing messages, retrieving user input, and setting up
default values for screen parameters, special keys, and help files. The next
three statements are window management statements. The last nine state-
ments 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.
CLEAR optionally clears specific screen fields, all screen fields, the
entire screen, or a window.
ERROR prints a message in reverse video on the Error line and rings
the terminal bell.
MESSAGE prints a message on the Message line.
PROMPT prints a message on the Prompt line and returns the user’s
response.

INFORMIX-4GL Programming 2-19

Screen Interaction

OPTIONS specifies the Message, Prompt, Form, and Comment lines

relative to the screen or current window, as well as any key
and help file designations. You can also specify a new Error
line with the OPTIONS statement, but the error line remains
relative to the screen.
OPEN creates a window, with or without a border, at a given loca-
WINDOW tion 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.
CURRENT specifies the current or ‘‘topmost’’ window. All input and
WINDOW output is done in the current window.
CLOSE closes the window that you specify, restoring the ‘‘topmost’’
WINDOW window (of those that remain) as the current window.
OPEN FORM opens the compiled screen form and associates an INFOR-
MIX-4GL identifier with the form.
DISPLAY displays the named form on the screen or in a window,
FORM displacing whatever was on the screen or window below the
Form line.
CLOSE FORM closes the file containing the named screen form and releases
its association with the INFORMIX-4GL identifier.
CONSTRUCT 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.
DISPLAY displays expressions and variables in fields of a screen form,
at a specific position on the screen, in a window, or on the
next line.
DISPLAY displays a program array to a screen array and allows
ARRAY scrolling through the array.
INPUT takes user-entered data from a screen form and puts the data
into program variables. You can specify sequences of state-
ments to be executed during the INPUT statement before or
after the cursor enters any field or after the user indicates
that entry is complete. You can also trap function or control
keys and specify an appropriate sequence of statements.
INPUT is an extension of the INPUT statement that takes data
ARRAY entered by a user into a screen array and puts the informa-
tion 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.

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.
START signals INFORMIX-4GL to initialize the report. Optionally,
REPORT you can specify the output device in the START REPORT
statement.
OUTPUT TO passes a row of the report variables to the report. This state-
REPORT ment is usually found within a FOREACH loop where the
report row is the current row of a query.
FINISH handles the end of report summaries and, if necessary, sec-
REPORT ond passes through the data so that aggregate values can be
calculated.

Error and Exception Handling

INFORMIX-4GL allows you to trap run-time errors and warnings, and user-
entered 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 condi-
tions, 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 difficulties in your program.
DEFER 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_flag and quit_flag to
determine whether the user has pressed the Interrupt or
Quit keys after these statements.

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 find 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 specifies 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 identifies the database that your program declares in
the DATABASE statement that precedes the first program block (the MAIN
program block, or the first 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 state-
ments are similar, extending to the end of the module, or else to the next
WHENEVER statement that specifies 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 file every time an error occurs.
The syntax for startlog( ) is
CALL startlog ( filename )

2-22 INFORMIX-4GL Programming

Data Validation

where filename is a quoted string that specifies the name of the error log file,
or a CHAR variable that evaluates to the name of the error log file. If you do
not want the error log file 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 file.
Chapter 6 describes these and three other 4GL library functions that deal
with errors:
err_print( ) If passed the error code, prints the message on the Error line.
err_get( ) If passed the error code, returns the message to a string
variable.
err_quit( ) 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 flag (int_flag for INTERRUPT and
quit_flag for QUIT) is set to non-zero and can be checked by the program. It
is the programmer’s responsibility to reset the flags 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 con-
trol leaves the INPUT statement and INFORMIX-4GL sets int_flag.
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 specification 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 con-
sistent 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 specified 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 prefix 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-defined
functions, operators, and keyword expressions. You can use the following
functions, operators, and keywords in expressions.

ASCII MDY( )
CLIPPED MONTH( )
COLUMN TIME
CURRENT TODAY
DATE UNITS
DATE( ) USING
DAY( ) WEEKDAY( )
EXTEND( ) YEAR( )
LENGTH( )
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 INFOR-
MIX-OnLine Programmer’s Manual for more information.

2-24 INFORMIX-4GL Programming

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

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

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.
integer-expr is a required positive integer expression that specifies the ini-
tial column number of the next item to be printed.

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 specified 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

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

Syntax
CURRENT [ first TO last ]

Explanation
CURRENT is a required keyword.
first is a qualifier that specifies the first field to be returned.
TO is a required keyword if you specify first and last.
last is a qualifier that specifies the last field to be returned.

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 first qualifier must specify a field that is more significant than or equal
to the last qualifier.
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 specific point in the execution of the 4GL
statement.
6. If no first TO last qualifiers are specified, the default qualifiers are
YEAR TO FRACTION(3).

2-30 INFORMIX-4GL Programming

Examples

7. The following qualifiers are valid:

Identifier Qualified Data
YEAR A number of years.
MONTH A number of months.
DAY A number of days.
HOUR A number of hours.
MINUTE A number of minutes.
SECOND A number of seconds.
FRACTION (n) 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

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( )

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

Syntax
DATE ( expr )

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

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( )

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.
dtime-expr is a required expression whose value is of type DATE or
DATETIME.

Examples
The first 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( )

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

Syntax
EXTEND ( value [ , first TO last ] )

Explanation
EXTEND is a required keyword.
value is a DATE or DATETIME value (column name, variable, or expres-
sion) of any valid precision.
first is an optional qualifier that specifies the first field in the result.
(See Note 5.)
TO is a required keyword if you include first and last qualifiers.
last is an optional qualifier that specifies the last field in the result. (See
Note 6.)

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 first TO last qualifiers are specified, the default qualifiers are YEAR
TO FRACTION(3).
3. The first qualifier must specify a field that is more significant than or equal
to the last qualifier.
4. If the value contains fields not specified by the qualifiers, the unwanted
fields are discarded.
5. If the first qualifier specifies a field to the left of (that is, more significant
than) what exists in value, the new fields are filled with values returned
by the CURRENT function.
6. If the last qualifier specifies a field to the right of (that is, less significant
than) what exists in value, the new fields are filled in with constant values.

INFORMIX-4GL Programming 2-35

Examples

A missing MONTH or DAY is filled in with 1, and the missing fields HOUR
to FRACTION are filled in with 0.
7. The following qualifiers are valid:
Identifier Qualified Data
YEAR A number of years.
MONTH A number of months.
DAY A number of days.
HOUR A number of hours.
MINUTE A number of minutes.
SECOND A number of seconds.
FRACTION (n) 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 field that is not present in a DATETIME
or DATE value, you cannot combine the two values with the addition ( + )
or subtraction ( - ) operators. You must first use the EXTEND function to
return an adjusted DATETIME value on which to perform the arithmetic
operation.

Examples
In the first example, the EXTEND function returns the MONTH and DAY fields
from a column that contains YEAR, MONTH, and DAY data. In this instance,
the YEAR field 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 fields
that are not present in the DATETIME variable t_stamp, so the EXTEND func-
tion 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 identifier 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 Programmer’s Manual for more information.

2-38 INFORMIX-4GL Programming

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.
expr1 is an expression that evaluates to an integer representing the num-
ber of the month (1-12).
expr2 is an expression that evaluates to an integer representing the num-
ber of the day of the month (1-28, 29, 30, or 31, depending on the
month).
expr3 is an expression that evaluates to a four-digit integer representing
the year.

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

INFORMIX-4GL Programming 2-39

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.
dtime-expr is a required expression of type DATE or DATETIME.

Notes
1. This function extracts the month from a DATE or DATETIME value, return-
ing 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 Bool-
ean 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

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

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

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

Syntax
expr UNITS qualifier

Explanation
expr is a number expression.
UNITS is a required keyword.
qualifier is the name of an INTERVAL field.

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 sub-
tracted from a DATETIME or INTERVAL expression, provided that the
UNITS operand follows the arithmetic operator (either + or - ) as the sec-
ond operand.
3. The qualifier can be any one of the following field keywords:
YEAR MONTH DAY
HOUR MINUTE SECOND FRACTION ( n )

Example
LET fortnite = CURRENT + 14 UNITS DAY

INFORMIX-4GL Programming 2-43

USING

Overview
The USING operator specifies a format for number, MONEY, or DATE expres-
sions. 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 is a required expression that specifies what USING is to
format.
USING is a required keyword.
format-string is a required quoted string that specifies how USING is to
format expr.

Formatting Number Expressions

The format-string consists of combinations of the following characters:
* & # < , . - + ( ) $. The characters - + ( ) $ will float. When a character ‘‘floats,’’
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 fills with asterisks ( * ) any positions in the display
field that would otherwise be blank.
& This character fills with zeros any positions in the display field
that would otherwise be blank.
# This character does not change any blank positions in the display
field. You can use this to specify a maximum width for a field.
< This character causes numbers in the field to be left-justified.
, 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 floats 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 floats to the rightmost position without interfer-
ing 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
floats to the rightmost position without interfering with the num-
ber 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 gener-
ally 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 floats
to the rightmost position without interfering with the number
being printed.
Refer to the ‘‘Examples’’ section for examples of formatting number expres-
sions. Since format strings interact with data to produce visual effects, some
readers may find 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 day of the month as a 2-digit number (01-31)
ddd day of the week as a 3-letter abbreviation (Sun through Sat)

mm month as a 2-digit number (01-12)

mmm month as a 3-letter abbreviation (Jan through Dec)

yy year as a 2-digit number in the 1900s (00-99)

yyyy year as a 4-digit number (0001-9999)
Figure 2-1 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 field,
INFORMIX-4GL fills the field with asterisks ( * ) to indicate an overflow.

Examples
The following example prints the balance field 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 fixes the currency symbol.
This example also uses the # and & fill characters. The # character provides
blank fill for unused character positions, while the & character provides zero
filling. 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 floats with the size of the number, so that it appears
immediately to the left of the most significant 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 Formatted Result
"mmddyy" 122589
"ddmmyy" 251289
"yymmdd" 891225
"yy/mm/dd" 89/12/25
"yy mm dd" 89 12 25
"yy-mm-dd" 89-12-25
"mmm. dd, yyyy" Dec. 25, 1989
"mmm dd yyyy" Dec 25 1989
"yyyy dd mm" 1989 25 12
"mmm dd yyyy" Dec 25 1989
"ddd, mmm. dd, yyyy" Mon, Dec. 25, 1989
"(ddd) mmm. dd, yyyy" (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 Formatted Result

"#####" 0 bbbbb
"&&&&&" 0 00000
"$$$$$" 0 bbbb$
"*****" 0 *****
"<<<<<" 0 bbbbb
(null string)

"<<<,<<<" 12345 12,345

"<<<,<<<" 1234 1,234
"<<<,<<<" 123 123
"<<<,<<<" 12 12

"##,###" 12345 12,345

"##,###" 1234 b1,234
"##,###" 123 bbb123
"##,###" 12 bbbb12
"##,###" 1 bbbbb1
"##,###" -1 bbbbb1
"##,###" 0 bbbbbb

"&&,&&&" 12345 12,345

"&&,&&&" 1234 01,234
"&&,&&&" 123 000123
"&&,&&&" 12 000012
"&&,&&&" 1 000001
"&&,&&&" 0 000000

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

(overflow)

"$$,$$$" 1234 $1,234

"$$,$$$" 123 bb$123
"$$,$$$" 12 bbb$12
"$$,$$$" 1 bbbb$1
"$$,$$$" 0 bbbbb$

",*" 12345 12,345

"**,***" 1234 *1,234
"**,***" 123 ***123
"**,***" 12 ****12
"**,***" 1 *****1
"**,***" 0 ******
Here the character b represents a blank or space.

INFORMIX-4GL Programming 2-49

Examples

Format String Data Value Formatted Result

"##,###.##" 12345.67 12,345.67

"##,###.##" 1234.56 b1,234.56
"##,###.##" 123.45 bbb123.45
"##,###.##" 12.34 bbbb12.34
"##,###.##" 1.23 bbbbb1.23
"##,###.##" 0.12 bbbbb0.12
"##,###.##" 0.01 bbbbbb.01
"##,###.##" -0.01 bbbbbb.01
"##,###.##" -1 bbbbb1.00

"&&,&&&.&&" 12345.67 12,345.67

"&&,&&&.&&" 1234.56 01,234.56
"&&,&&&.&&" 123.45 000123.45
"&&,&&&.&&" 0.01 000000.01

"$$,$$$.$$" 12345.67 *********

(overflow)
"$$,$$$.$$" 1234.56 $1,234.56
"$$,$$$.##" 0.00 $.00
"$$,$$$.##" 1234.00 $1,234.00
"$$,$$$.&&" 0.00 $.00
"$$,$$$.&&" 1234.00 $1,234.00

"-##,###.##" -12345.67 -12,345.67

"-##,###.##" -123.45 -bbb123.45
"-##,###.##" -12.34 -bbbb12.34
"--#,###.##" -12.34 -bbb12.34
"---,###.##" -12.34 -bb12.34
"---,-##.##" -12.34 -12.34
"---,--#.##" -1.00 -1.00

"-##,###.##" 12345.67 12,345.67

"-##,###.##" 1234.56 1,234.56
"-##,###.##" 123.45 123.45
"-##,###.##" 12.34 12.34
"--#,###.##" 12.34 12.34
"---,###.##" 12.34 12.34
"---,-##.##" 12.34 12.34
"---,---.##" 1.00 1.00
"---,---.--" -.01 -.01
Here the character b represents a blank or space.

2-50 INFORMIX-4GL Programming

Examples

Format String Data Value Formatted Result

"----,---.&&" -.01 -.01

"-$$$,$$$.&&" -12345.67 -$12,345.67
"-$$$,$$$.&&" -1234.56 -b$1,234.56
"-$$$,$$$.&&" -123.45 -bbb$123.45
"--$$,$$$.&&" -12345.67 -$12,345.67
"--$$,$$$.&&" -1234.56 -$1,234.56
"--$$,$$$.&&" -123.45 -bb$123.45
"--$$,$$$.&&" -12.34 -bbb$12.34
"--$$,$$$.&&" -1.23 -bbbb$1.23

"----,--$.&&" -12345.67 -$12,345.67

"----,--$.&&" -1234.56 -$1,234.56
"----,--$.&&" -123.45 -$123.45
"----,--$.&&" -12.34 -$12.34
"----,--$.&&" -1.23 -$1.23
"----,--$.&&" -.12 -$.12

"$,.&&" 12345.67 $*12,345.67

"$***,***.&&" 1234.56 $**1,234.56
"$***,***.&&" 123.45 $****123.45
"$***,***.&&" 12.34 $*****12.34
"$***,***.&&" 1.23 $******1.23
"$***,***.&&" .12 $*******.12

"($$$,$$$.&&)" -12345.67 ($12,345.67)

"($$$,$$$.&&)" -1234.56 (b$1,234.56)
"($$$,$$$.&&)" -123.45 (bbb$123.45)
"(($$,$$$.&&)" -12345.67 ($12,345.67)
"(($$,$$$.&&)" -1234.56 ($1,234.56)
"(($$,$$$.&&)" -123.45 (bb$123.45)
"(($$,$$$.&&)" -12.34 (bbb$12.34)
"(($$,$$$.&&)" -1.23 (bbbb$1.23)

"((((,(($.&&)" -12345.67 ($12,345.67)

"((((,(($.&&)" -1234.56 ($1,234.56)
"((((,(($.&&)" -123.45 ($123.45)
"((((,(($.&&)" -12.34 ($12.34)
"((((,(($.&&)" -1.23 ($1.23)
"((((,(($.&&)" -.12 ($.12)

Here the character b represents a blank or space.

INFORMIX-4GL Programming 2-51

Examples

Format String Data Value Formatted Result

"($$$,$$$.&&)" 12345.67 $12,345.67

"($$$,$$$.&&)" 1234.56 $1,234.56
"($$$,$$$.&&)" 123.45 $123.45
"(($$,$$$.&&)" 12345.67 $12,345.67
"(($$,$$$.&&)" 1234.56 $1,234.56
"(($$,$$$.&&)" 123.45 $123.45
"(($$,$$$.&&)" 12.34 $12.34
"(($$,$$$.&&)" 1.23 $1.23

"((((,(($.&&)" 12345.67 $12,345.67

"((((,(($.&&)" 1234.56 $1,234.56
"((((,(($.&&)" 123.45 $123.45
"((((,(($.&&)" 12.34 $12.34
"((((,(($.&&)" 1.23 $1.23
"((((,(($.&&)" .12 $.12
Here the character b represents a blank or space.

2-52 INFORMIX-4GL Programming

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.
dtime-expr is a required expression of type DATE.

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( )

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.
dtime-expr is a required expression of type DATE or DATETIME.

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 trans-
parent function-calling mechanism, INFORMIX-4GL requires that C functions
follow a calling convention that allows data to be passed between the INFOR-
MIX-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
section“RDS 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 predefined way by both INFORMIX-4GL programs and C functions. You
can perform two classes of operations on a stack:
push to add a variable to the stack
pop to retrieve a variable from the stack
The stack acts as a LIFO (last-in, first-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 specific 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 param-
eters 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 Pushing Functions Argument Types

popint(&i) retint(i) int i;
popshort(&s) retshort(s) short s;
poplong(&l) retlong(l) long l;
popflo(&f) retflo(&f) float f;
popdub(&d) retdub(&d) double d;
popquote(str, len) retquote(str) char *str;
int len;
popdec(&dm) retdec(&dm) dec_t dm;
popdtime(&dt, qual) retdtime(&dt) dtime_t dt;
int qual;
popinv(&inv, qual) retinv(&inv) intrvl_t inv;
int qual;
Note: INFORMIX-OnLine supports additional functionality. Refer to the
INFORMIX-OnLine Programmer’s Manual for more information.
Here len is the buffer size of the string to which str points, and qual is the qual-
ifier of the DATETIME or INTERVAL value that will be received by destination
variable dt or inv.
Your first 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 first pop c, and
then b, and finally a. You must use the library function that is appropriate for
the data type of the receiving variable. After the function is called, INFOR-
MIX-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 defined 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 first 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 com-
puter. Two arguments are explicitly passed to the function: the source string
and its length. INFORMIX-4GL automatically passes the number of argu-
ments 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 msg_number, retcode */

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

char input[80]; /* 4gl and C function must agree on data */

int msg_number; /* types and the order that arguments are */
int len, retcode; /* placed on the stack */

/* 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 func-
tions 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

3
Chapter Overview 5
Relational Databases 5
SQL Identifiers 6
Owner Naming 7
Database Data Types 8
SQL Statement Summary 10
Data Definition 11
Data Manipulation 12
Cursor Management 13
SELECT Cursors 13
Associating a Cursor with a SELECT Statement 14
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 Identifiers 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
User Status and Privileges 41
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 49
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 57
Views 57
Creating and Deleting Views 58
Querying Through Views 58
Modifying Through Views 59
Privileges with Views 60
Data Constraints Using Views 60

3-2 Using SQL

Outer Joins 61
Table Access by ROWID 62
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 Infor-
mix 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 lan-
guage 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 state-
ments 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 specific 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 define the
database dictionary. It also contains the tables that constitute the database.
Each of these tables is represented by data files and index files, with the
extensions .dat and .idx, respectively. The system catalogs are described
in Appendix B.

Using SQL 3-5

SQL Identifiers

You have the option of specifying a MODE ANSI database. A database created
or started as MODE ANSI supports implicit transactions and enforces owner-
naming. (See the section “Data Integrity” for more information about trans-
actions 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 flag in the command line that invokes the 4GL
compiler, you receive a compile-time warning, in the form of messages
to a diagnostic file, 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 defined (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 Identifiers
An SQL identifier is the name of an object. It can consist of letters, numbers,
and underscores ( _ ). The first character must be a letter. Unless otherwise
indicated, an identifier can have from one to 18 characters.
Database A database name is an identifier that can have from one to 10
characters.
Table A table name is an identifier that must be unique within the
database. (In a MODE ANSI database, the owner and table
combined must be unique within the database.)
Column A column name is an identifier that must be unique within a
table; there can be duplicate column names within a data-
base. When column names within different tables are not
unique, use the notation table.column to specify the intended
column. If you intend to define an INFORMIX-4GL record
like a table, the first 8 characters of each column name in the
table must be unique within the table.
If there is an ambiguity because an INFORMIX-4GL identifier and an SQL
identifier are the same, INFORMIX-4GL assumes that the identifier 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, prefix the SQL identifier with an ‘‘at’’ sign ( @ ).
For example, if lname is defined 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 qualified 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 first character is a digit. The quoted
string can be up to 8 characters long.
• object is a valid identifier for a table, view, index, synonym, or constraint.
The identifier 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 own-
ership 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 modifies 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 first SELECT statement but not in the sec-
ond. Because of the quotes, the case distinction is preserved in the first
SELECT; therefore, the first 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 prefix. 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 prefix.

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
defined in Chapter 2. The valid SQL data types are as follows:
CHAR [(n)] is a character string of length n (where 1 ≤ n ≤ 32,511).
If you do not specify n, CHAR(1) is assumed.
CHARACTER is a synonym for CHAR.
SMALLINT is a whole number from -32,767 to +32,767.
INTEGER is a whole number from -2,147,483,647 to
+2,147,483,647.
INT is a synonym for INTEGER.
DECIMAL [(m[,n])] is a decimal floating point number with m (≤ 32)
significant 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
fixed-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 floating decimal. DECIMAL(m)
variables have a precision of and a range in absolute
value from 10-128 to 10126 If no parameters are desig-
nated, DECIMAL is treated as DECIMAL(16), a floating
decimal.
DEC is a synonym for DECIMAL.
NUMERIC is another synonym for DECIMAL.
SMALLFLOAT is a floating-point number corresponding to the float
C data type. The range of values for a SMALLFLOAT
data type is the same as the range of values for the
C float data type on your machine.
REAL is a synonym for SMALLFLOAT.
FLOAT [(n)] is a floating-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 pro-
vided for compatibility with ANSI standards.)
DOUBLE PRECISION is a synonym for FLOAT.
MONEY [(m [,n] )] 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 defined as DECIMAL (m, 2)
and, if no parameter is given, MONEY defaults to
DECIMAL (16, 2). Regardless of the number of param-
eters, the data type MONEY is always treated as a
fixed decimal number.
SERIAL [ (n) ] is a sequential integer assigned automatically by
INFORMIX-4GL. You can assign an initial value n.
The default starting integer is 1.
DATE is a date entered as a character string in one of the for-
mats described in Chapter 2, and stored as an integer
number of days since December 31, 1899.
Using SQL 3-9
SQL Statement Summary

DATETIME stores a moment in time with the precision first to last.

first TO last A DATETIME column is entered as a character string
in one of the formats described in Chapter 2, record-
ing 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
fields: YEAR, MONTH, DAY, HOUR, MINUTE,
SECOND, and FRACTION(n) of a second. DATETIME
is described in greater detail in Appendix J.
INTERVAL stores a span of time with the precision first to last. An
first TO last 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 fields from first to
last. An INTERVAL column consists of a contiguous
sequence of one of the following two lists of fields:
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.
Note: INFORMIX-OnLine supports additional data types. Refer to the INFOR-
MIX-OnLine Programmer’s Manual for more information.

SQL Statement Summary

Six different types of SQL statements are used with INFORMIX-4GL:
• Data definition
• Data manipulation
• Cursor management
• Dynamic management
• Data access
• Data integrity

3-10 Using SQL

Data Definition

Data Definition
Data definition 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 defining
program variables LIKE columns in the database.
CREATE creates a database directory, sets up the system catalogs, and
DATABASE makes the new database the current database. There can be no
more than one current database at any time.
DATABASE selects a database and makes it the current database. There
can be no more than one current database at any time.
CLOSE closes the current database files and leaves no database
DATABASE current. The only SQL statements permitted when there
is no current database are:
• CREATE DATABASE
• DATABASE
• DROP DATABASE
• START DATABASE
DROP deletes all tables, indexes, and system catalogs. If no other
DATABASE files are present in the database subdirectory, the subdirec-
tory is also deleted.
CREATE creates a table and defines the columns and their data types.
TABLE
ALTER adds or drops columns and constraints from a table, and
TABLE modifies data types of existing columns.
RENAME changes the name of a table, replacing the old name with the
TABLE new name in the system catalogs.
DROP deletes all data and indexes for a table and erases its entry in
TABLE the system catalogs.
CREATE defines a table selected from rows and columns of existing
VIEW 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.
DROP deletes the definition of the view from the system catalogs,
VIEW along with any views defined in terms of the one that is
dropped. The underlying tables are unaffected.
CREATE defines an alternative name for a table or a view. For INFOR-
SYNONYM MIX-4GL programs, the creator of the synonym is the user
who runs the program that creates the synonym.

Using SQL 3-11

Data Manipulation

DROP deletes a synonym from the system catalogs.

SYNONYM
RENAME changes the name of a column, replacing the old name with
COLUMN the new name in the system catalogs.
CREATE creates an index on one or more columns of a table. See the
INDEX section “Indexing Strategy” later in this chapter for more
information on indexes.
ALTER clusters a table in the order of an existing index or releases
INDEX an index from the cluster attribute.
DROP deletes an existing index, removing it from the system
INDEX catalogs.
UPDATE updates the system catalogs by determining and inserting
STATISTICS 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 deletes one or more rows from a table.
INSERT adds one or more rows to a table.
LOAD inserts rows from an operating system file.
SELECT retrieves data from one or more tables.
UNLOAD copies rows to an operating system file.
UPDATE modifies 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 defined 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
identifier as the corresponding columns in the items table. There is no conflict
here, since the prefix @ 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 ref-
erenced 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 first 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 ran-
dom order.
• A regular or SCROLL cursor can be specified as WITH HOLD. Unlike reg-
ular 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 file. 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 specified 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
specified 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 state-
ment. The OPEN statement causes the SELECT statement to run
with the current program variables and leaves the cursor pointing
just before the first 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.
FETCH advances the cursor to the specified row (either FIRST, LAST, NEXT,
PRIOR or PREVIOUS, ABSOLUTE n, or RELATIVE m) and retrieves

3-16 Using SQL

SELECT Cursors

the values from that row. If a FETCH statement moves the cursor
before the first row or after the last row, the error variable status
has the value NOTFOUND (= 100), as does the SQLCODE compo-
nent 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 num-
ber 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 first row, and assigns to the program variables order_num and
order_date the values of the columns order_num and order_date in the
first 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 first row) of the active set. The cursor remains pointing to the first 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 dis-
solved. 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 exe-
cute 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 state-
ment 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 cust_rec

IF status <> 0
EXIT FOREACH

-- 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 state-
ment 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 customer’s 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 file
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
file instead of from the database.
The temporary file allows you to retrieve rows in a random order. It also
means, however, that subsequent changes to the database may not be
reflected 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 specified 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 first row of the
active set.
• The FETCH FIRST statement attempts to retrieve the first 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 first 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 vari-
able 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 cur-

3-22 Using SQL

SELECT Cursors

sor to the first row, and displays a message if the value of the sta-
tus variable indicates that the cursor has moved beyond the first
row of the active set. The DISPLAY BY NAME statement displays
on the screen the row retrieved by the appropriate FETCH
statement.
First includes a FETCH FIRST statement that retrieves the first row in the
active set and displays it on the screen.
Last includes a FETCH LAST statement that retrieves the last row in the
active set and displays it on the screen.
Exit includes an EXIT MENU statement that terminates the MENU
statement.
All FETCH statements except the default FETCH NEXT statement require that
you first DECLARE a SCROLL cursor. The default FETCH statement works
with all cursors.
Note: When you open a cursor that identifies a SELECT statement containing a pro-
gram 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 first
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 transac-
tion, and you must explicitly CLOSE the cursor.

Using SQL 3-23

SELECT Cursors

The following example outlines a typical program structure that uses a cur-
sor 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 first 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 first 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 bound-
aries. 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 Programmer’s 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 flag.

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 efficiently 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.
OPEN sets up an insert buffer for an INSERT cursor.
PUT stores a row in the INSERT buffer for later insertion into the
database. When you fill the buffer (by executing a series of
PUT statements), INFORMIX-4GL automatically inserts the
rows into the appropriate table as a block.
FLUSH 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.
CLOSE flushes the insert buffer and closes the INSERT cursor.
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 cus-
tomers 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. Specifically, 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, INFOR-
MIX-4GL closes the INSERT cursor before leaving the program. (Any remain-
ing 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 defined statements.
There are four dynamic management statements:
PREPARE takes a character string, interprets it as an SQL statement,
and assigns it to a statement identifier. Subsequent dynamic
management statements refer to the SQL statement through
the statement identifier.
EXECUTE runs the previously PREPAREd statement associated with
the statement identifier. Use EXECUTE for all PREPAREd
statements except the following statements:
• SELECT statements

3-28 Using SQL

Preparing Statements

• INSERT statements that use an insert cursor

DECLARE has options that DECLARE a cursor for a PREPAREd SELECT
or INSERT statement.
FREE 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 identifiers 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. Specifically,
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 FETCH PREPARE
DECLARE LOAD SELECT (with INTO variable clause)
EXECUTE OPEN 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 state-
ment, 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 specifies an INSERT statement. When you OPEN this cur-
sor, INFORMIX-4GL automatically PREPAREs the INSERT statement. Implicitly
PREPAREd statements become an issue only if you exceed the engine resources allo-
cated 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. Specifically, the question mark can represent a value or expression in
a character string, but not an SQL identifier (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 state-
ment. (See the section “Executing PREPAREd Statements” later in this chap-
ter 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 state-
ment 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 con-
catenates a character string containing part of the SELECT statement to the
variable cust_num, which contains a customer number that the user sup-
plies. 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 Identifiers

You must use PREPARE with a character variable to PREPARE a statement that
requires data for an SQL identifier (such as a column name, table name, user-
name, 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 identifier(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 specified 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

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 char-
acter 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 INFOR-
MIX-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 substi-
tutes 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 identifier 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 engine’s
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 first 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 specific columns within a
table only when the DBA or the owner of the table specifically 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 grants database access privileges to specific users or to the
public.
REVOKE removes database access privileges from specific users or
from the public.
LOCK limits access to the table to the current user only, or allows
TABLE other users only to read the table. Use the LOCK TABLE state-
ment 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 and is not MODE ANSI, you must issue a BEGIN
WORK statement before you can issue the LOCK TABLE
statement.
UNLOCK restores access to a previously LOCKed table.
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 identifies 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 per-
son. 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, includ-
ing 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 responsi-
bility for maintaining the database.
INFORMIX-4GL allows the CONNECT and RESOURCE privileges to be
granted TO PUBLIC, in addition to specifically 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 specific 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 specifically 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 specified
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 pro-
gram 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 transac-
tions. 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:
BEGIN marks the start of a transaction (if the database is not
WORK MODE ANSI).
COMMIT marks the end of a transaction by authorizing all database
WORK changes since the transaction began.
ROLLBACK marks the end of a transaction by revoking all database
WORK changes since the transaction began.
START initiates a new transaction log file and (optionally)
DATABASE converts a database to MODE ANSI.
ROLLFORWARD uses a transaction log file to restore a database from
DATABASE backup.
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 file that records all modifi-

3-42 Using SQL

Transactions

cations to the database. If you also specify the MODE ANSI option, transac-
tions 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, par-
ticularly if the error occurs within a series of closely related database opera-
tions 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 modified. Without transactions, you
must take explicit action to restore the updated rows. (The “Audit Trails” sec-
tion later in this chapter describes a recovery procedure for databases with-
out 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 file. 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 modification 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 transac-
tion. Each statement, if it executes successfully, is committed, and the data-
base 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, first 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 definition
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 satisfied that
the series of operations has produced the desired results. If you are not satis-
fied with the results, you can terminate the transaction with a ROLLBACK
WORK statement. With the exceptions stated in the next paragraph, this state-
ment restores the database to the state that existed immediately before the
transaction began. Both the COMMIT WORK and the ROLLBACK WORK state-
ments release all row and table locks, making the data accessible for modifi-
cation by others.
On INFORMIX-SE, you cannot roll back GRANT or REVOKE statements, nor
any of the data definition statements. These statements alter the number or
names of tables, or change the number, names, data types, or indexes of col-
umns. If they were executed successfully, they are committed, and the ROLL-
BACK 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

The transaction log file can become quite large and, periodically, the DBA will
want to archive it on tape and initiate another log file. At the same time, the
DBA should also create a backup of your database. In general, every log file
must have a corresponding archive copy of the database. After backing up
the log file and the database, the DBA must specify an empty log file. To reuse
the same log file, the DBA should create an empty log file 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 file, 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 file 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 files 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 file that contains a history of all additions, deletions,
updates, and manipulations to a database table. An audit trail serves a pur-
pose similar to that of a transaction log: each is used to maintain a record of
modifications 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 creates an audit trail for a table.
DROP AUDIT 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 file 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 file and pathname is the full pathname of the audit trail file. The audit trail
file 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 file whenever you want. Drop and cre-
ate the audit trail files just before you make a complete backup of the device
containing the data file. 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 file. You must first 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 file. Then run the CREATE AUDIT statement to start
a new audit trail file. Finally, make a new backup copy of the table.

3-46 Using SQL

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 transac-
tion, 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
modifications to several rows of a table either succeed entirely or fail without
any effect. You can use an audit trail file 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 facil-
ities 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 con-
flicting 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
file ‘‘wins’’ and overwrites changes by the other user.
The following SQL statements control locking:
LOCK limits access to the table to the current user only or allows other
TABLE users only to read the table. Use the LOCK TABLE statement
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.
UNLOCK restores access to a previously locked table.
TABLE

Using SQL 3-47

Row-Level Locking

SET LOCK alters the locking strategy, either to fail when a row is already
MODE 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 file-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 definition 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 INFOR-
MIX-OnLine Programmer’s Manual for more information.

Row-Level Locking
Ordinarily, INFORMIX-4GL locks a row when you execute an UPDATE state-
ment, 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 pro-
gram 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 finishes, 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 specifies
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
modifications are made to the database, or a ROLLBACK WORK, where none
of the modifications 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 opera-
tions that affect every row in a table. If the operations must be completed as
a single transaction, it may be more efficient 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 auto-
matically 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 row-
level locking (as described in the previous section) is not sufficient.

Using SQL 3-49

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 INFOR-
MIX-OnLine Programmer’s 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, significant 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 modified. 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 conflict between needs is to take a dynamic
approach to indexing. One of the advantages of an Informix relational data-
base 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 anticipa-
tion 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 file 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 INFOR-
MIX-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 sin-
gle 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 sev-
eral 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 file 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 file for each sub-
sequent query. The recorded information includes the order of table access,
how filters 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 difficult to predict the actual order of actions taken by the optimizer,
thus making it difficult 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 tempo-
rary index on the table with the larger number of rows before performing the
join. The index disappears when the query finishes. 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 physi-
cally 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 file 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 benefit 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 clus-
tered index on a table at any given time. You can change the physical order
to reflect a different index by executing two ALTER INDEX statements:
1. Execute an ALTER INDEX TO NOT CLUSTER statement to release the clus-
ter attribute from the first 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 char-
acter values between blanks and NULL. You do not need to know how
INFORMIX-4GL implements the value NULL to make use of it.

By definition, type SERIAL columns can never contain the NULL value. Col-
umns 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 pre-
vent 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 num-
ber 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 val-
ues, 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 ? OR T F ? NOT

T T F ? T T T T T F
F F F F F T F ? F T
? ? F ? ? T ? ? ? ?
Figure 3-1 Combining Boolean Expressions

The NULL in WHERE Clauses

If the Boolean expression in a WHERE clause evaluates to UNKNOWN for a par-
ticular row, INFORMIX-4GL treats the search condition as not satisfied 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 cho-
sen. 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 (Incorrect)
column != NULL (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 ascend-
ing ( ASC ), the NULL values come first; 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

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 filled with NULL values. Simi-
larly, 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 col-
umns. 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 pro-
tect 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 state-
ment. 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 condi-
tions, 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 deter-
mined by a SELECT statement that returns the ‘‘table’’ that defines the view.
You cannot use the UNION operator in the definition of a view. (See Chapter 7
for the definition 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 defining 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 define 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 defined 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 first combines the view-defining SELECT state-
ment 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-defining
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 definition
involves joins, the GROUP BY clause, the DISTINCT keyword, or an aggre-
gate function. If any of these features appears in the view definition, the
creator of the view cannot execute INSERT, DELETE, or UPDATE state-
ments on the view. You can define 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 data-
base 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
benefit 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 under-
lying 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 defined
the view in terms of that column, INFORMIX-4GL issues an error if you sub-
sequently 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 limita-
tions 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 defined 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 satisfies pre-assigned limitations. Through a form in INFOR-
MIX-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 define allowed value ranges dynamically, based on the
values in other columns or even in other tables. The existence of views and,
specifically, 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 first 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 modification 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 dom-
inant table before projecting the desired columns. To illustrate, let a be a col-
umn 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 tab2.b
2 4
3 2
5 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 b
2 2
3 -
5 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 satisfies 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 inter-
nal record number. This feature is useful when there is no other unique col-
umn 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 significance to the sequential
values of ROWID.

3-62 Using SQL

SQLCA Record

SQLCA Record
Proper database management requires that all logical sequences of state-
ments 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 RECORD
SQLCODE INTEGER,
SQLERRM CHAR(71),
SQLERRP CHAR(8),
SQLERRD ARRAY [6] OF INTEGER ,
SQLAWARN CHAR (8)
END RECORD
SQLCODE indicates the result of executing an SQL statement. It is set to
zero for a successful execution of most statements and to NOT-
FOUND ( = 100 ) for a successfully executed query that returns
zero rows or for a FETCH that seeks beyond the end of an active
set.
SQLCODE is negative for an unsuccessful execution.
INFORMIX-4GL sets the global variable status equal to SQL-
CODE after each SQL statement. See “Error Messages” after the
appendixes for the error codes.
SQLERRM is not used at this time.
SQLERRP is not used at this time.
SQLERRD an array of six variables of type INTEGER
SQLERRD[1] is not used at this time.
SQLERRD[2] is the SERIAL value returned or ISAM error
code.
SQLERRD[3] is the number of rows processed.
SQLERRD[4] is the estimated CPU cost for query.

Using SQL 3-63

SQLCA Record

SQLERRD[5] is the offset of error into the SQL statement.

SQLERRD[6] 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) fol-
lowing 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 remain-
ing warning characters.
SQLAWARN[2] is set to W if one or more data items was trun-
cated to fit 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 pro-
gram 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 float-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

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 con-
stant 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 define 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 section“Cursor 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 Specification File 4
DATABASE Section 7
SCREEN Section 9
Textual Information 11
Display Fields 11
Graphics Characters in Forms 13
TABLES Section 15
4
ATTRIBUTES Section 17
Fields Linked to Database Columns 18
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
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 Programmer’s 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 pro-
gram, you must create a form specification file and use FORM4GL to compile
this file. The form specification file is an ASCII file that contains the screen for-
mat and the instructions to INFORMIX-4GL about how to display the data.
The first and longest section of this chapter, “Structure of a Form Specifica-
tion File,” describes the function and syntax of each of the required and
optional components of a 4GL form specification file. 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 fields of 4GL applications.
The section “Creating and Compiling a Form” describes how to use
FORM4GL to compile form files for use in INFORMIX-4GL programs. The last
section, “Using PERFORM Forms in INFORMIX-4GL” describes what hap-
pens when an INFORMIX-4GL program uses screen forms designed for PER-
FORM, the screen transaction program of INFORMIX-SQL.

Note: The FORM4GL syntax for forms that you design to work with INFOR-
MIX-4GL is different in several significant 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 Specification File

An INFORMIX-4GL form specification file 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 specification file 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 spec-
ify the position of the screen fields for data entry and display, and any
additional text or graphic characters.
• TABLES Section: A TABLES section must follow the SCREEN section if you
define any field with the name of a column in a database table. The
TABLES section identifies all the tables whose columns are associated
with screen fields in the ATTRIBUTES or INSTRUCTIONS sections, and
defines aliases for any table names or synonyms that require an owner
qualifier.
• ATTRIBUTES Section: The ATTRIBUTES section describes each field on
the form and assigns names to fields. The field specifications 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 field delimiters and can define screen records and
screen arrays.
Each section must begin with the keyword for which it is named. After you
create a form specification file, 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 fields of the screen form, as is illus-
trated 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 Specification File

A FORM4GL form specification file has this structure:

DATABASE
{ database-name | FORMONLY } [ WITHOUT NULL INPUT ]

SCREEN [ SIZE lines [ BY cols ] ]

{
[text] [ [field-tag] ] [graphics-char]
...
}
[ END ]

[ TABLES
[ tab-alias = [ owner. ] table ]
...
[ END ] ]

ATTRIBUTES
field-tag =
{ table.column
| FORMONLY. field-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 file, rather
than conventional symbols to mark optional terms:
• the set of braces ( { } ) in the SCREEN section
• the inner brackets ( [ ] ) around field-tag in the SCREEN section
• the inner brackets ( [ ] ) around n in the INSTRUCTIONS section
The next five 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 Specification File

Example
Figure 4-1 illustrates the overall structure of form specification files:
DATABASE stores

SCREEN
{
--------------------------------------------------------------------------
CUSTOMER INFORMATION:
Customer Number: [c1 ] Telephone: [c10 ]
...

SHIPPING INFORMATION:
Customer P.O.: [o20 ]

Ship Date: [o21 ] Date Paid: [o22 ]

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)
Figure 4-1 Sections of a Form Specification File

In this example, the screen form will display columns from several tables in
the stores database. The file is for a default physical screen size (24 lines of 80
characters) and includes all five 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 fields. The ellipsis
notation ( . . . ) in those sections is a typographic device to simplify this
illustration.

4-6 Form Building and Compiling

DATABASE Section

Overview
The DATABASE section of a form specification file identifies 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 specification file.
database-name is the name of a database that contains columns used to
define display fields of the form.
WITHOUT are keywords to indicate that database-name does not support
NULL INPUT NULL values.
FORMONLY is a keyword to indicate that the screen form is not associ-
ated with any database.

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 fields that have no other defaults, this option causes
INFORMIX-4GL to display zeros as default values for number and
INTERVAL fields, and blanks for character fields. 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 specification file. Use the table name formonly in
the ATTRIBUTES section in naming fields that are not linked to specific
columns of a database.

Form Building and Compiling 4-7

DATABASE Section

Examples
The following DATABASE section specifies that any columns referenced in
the TABLES section are in the stores demonstration database:
database
stores
The next example of a DATABASE section specifies that the screen form is not
associated with any database:
database
formonly

4-8 Form Building and Compiling

SCREEN Section

Overview
The SCREEN section of the form specification file specifies the vertical and
horizontal dimensions of the physical screen, and the position of display
fields 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 is a required keyword to mark the beginning of the SCREEN
section.
SIZE is an optional keyword to specify the vertical and horizontal
dimensions of the terminal screen.
lines is an integer that specifies the total number of lines of
characters (measured vertically) that the terminal screen can
display. The default is 24 lines.
BY is an optional keyword to specify how many characters
(measured horizontally) a line can display.
cols is an integer that specifies 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 fields and optional text and graphics
screen-layout characters that define 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.
END is an optional keyword to mark the end of the SCREEN
section.

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 Programmer’s Environment, as
described near the end of this chapter, these SIZE defaults appear
explicitly in the file.
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 defined as above, and form-name is the filename
(without the .per extension) of a form specification file.
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. INFOR-
MIX-4GL does not support multiple-page forms, so any lines beyond the
first page will overlay the last line of the first page if your screen-layout is
too large for your screen. (Create several form specification files if you
need to display more data than can fit 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 file specified.
6. The screen-layout must be enclosed in braces ( { } ). It consists of display
fields and (optionally) textual information and graphics characters. Display
fields must be indicated by brackets ( [ ] ) that define the field length and
the position within a line of the form, and by field tag labels within the
field.
7. Do not use braces as comment indicators in the screen-layout.
8. As in the other sections of a form specification file, 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 figure 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
specified here are reserved for the system.)
SCREEN SIZE 39 BY 80
{
.
.
.
Text, display fields, and graphic characters Screen layout
.
.
.
}
[ END ]

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 fields, or otherwise
improve the display. Except for the displacements described later in ‘‘Graph-
ics Characters in Forms,’’ position in the screen layout determines where text
appears on the screen. Text cannot overlap display fields, but the PICTURE
attribute (described in “Attributes Syntax” later in this chapter) can specify
literal characters within CHAR fields.

Display Fields
You can indicate where data will be displayed on the screen by using brackets
( [ ] ) to delimit fields in the screen layout. You must label each field with an
associated field tag to identify the field.

Syntax
[fieldtag ]

Explanation
[ ] are delimiters for a field. The width of the field 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.)
fieldtag is the field tag that labels the display field.

Form Building and Compiling 4-11

SCREEN Section

Notes
1. Each field must have a field tag, enclosed within brackets.
2. The field tag is from 1 to 50 characters long. It must fit within the brackets.
The first character must be a letter. The rest of the field tag can include
letters, numbers, and underscores ( _ ).
3. Field tags are labels; they are not the same as field names. The
ATTRIBUTES section links each field tag to a field name.
4. The same field tag can be used at more than one position in the SCREEN
section of the form specification, if you want the same information to
appear in more than one screen field, or if you define a multiple-line field,
or a screen array. (Multiple-line fields and screen arrays are described
later in this chapter.)
5. The case of a field tag is ignored (so a1 and A1 are the same).
6. You can give single-character fields the tags a through z (so a form can
include no more than 26 single-character fields.)
7. In a default form specification file, the widths of all fields 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 specification files.)
8. If you create your own form, you normally should set the width of each
display field in the SCREEN section to be equal to the width of the pro-
gram 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 field is too small
to display an assigned number, INFORMIX-4GL fills the field with
asterisks ( * ) to indicate the overflow.
10. Fields intended to display character data can be shorter than the defined
column length. INFORMIX-4GL fills a field from the left, and truncates
from the right any character string that is longer than the field to which it
is assigned. Through subscripting, you can assign portions of a character
column to one or more fields. (See the “ATTRIBUTES Section” later in this
chapter.)
11. If you edit and modify the default form specification file or create a new
file, you can verify that the field 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 file 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 fields in a
screen layout.

Example
The SCREEN section listed below appears in the orderform.per form specifi-
cation file in the INFORMIX-4GL demonstration application. This uses
default screen dimensions (24 by 80). Notice the use of textual information for
field labels, a screen title, and ornamental lines. (The “INSTRUCTIONS Sec-
tion” later in this chapter describes how repeated field tags are used in forms
that define 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 Purpose
p Use p to mark the upper-left corner.
q Use q to mark the upper-right corner.
b Use b to mark the lower-left corner.
d 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
specifications in the termcap or terminfo files, respectively. INFORMIX-4GL
substitutes the corresponding graphics characters when you display the
compiled form.
Once the form has the desired configuration, use the \g string to indicate
when to begin graphics mode and when to end graphics mode.
Insert a \g string before the first p, q, d, b, hyphen, or vertical bar that repre-
sents 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 first graphics character in the line, and push
the remaining characters to the right. The process of indicating graphics dis-
torts 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 specification file. 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 files must include
entries for the following variables:
termcap:
gs the escape sequence for entering graphics mode.
ge the escape sequence for leaving graphics mode.
gb the concatenated, ordered list of ASCII equivalents for the six
graphics characters used to draw the border.
terminfo:
smacs the escape sequence for entering graphics mode.
rmacs the escape sequence for leaving graphics mode.
acsc 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 ter-
mcap or terminfo files to support these graphics characters.

4-14 Form Building and Compiling

TABLES Section

Overview
The third section of the form specification file 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
prefix if the form will be run by users other than owner. If a prefix 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 specification file. 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.
tab-alias is the table alias in the form specification file.
owner is the username of whoever created tabname.
table is the identifier or synonym of table in its database.
END is an optional keyword to end the TABLES section.

Notes
1. If the DATABASE section specifies FORMONLY, no TABLES section is
needed unless you give a field the VALIDATE LIKE or DISPLAY LIKE
attribute in the ATTRIBUTES section, or type a field 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 specified in the TABLES section.

Form Building and Compiling 4-15

TABLES Section

4. The table identifier is the name listed in the tabname column of the systa-
bles 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 file cannot qual-
ify table with an owner prefix. You must define a tab-alias to reference the
owner of a table or synonym. (This alias can be the same identifier 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 specification file can reference screen fields as column or as table.
column, but they cannot specify owner. table. column. You cannot specify
table. column as a field name if you define 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 file orderform.per in Appendix A lists four tables:
TABLES customer orders items stock
The following TABLES section specifies aliases for two tables:
TABLES tab1 = refdpt.booktab
tab2 = athdpt.balltab
Note: INFORMIX-OnLine supports additional functionality. Refer to the INFOR-
MIX-OnLine Programmer’s Manual for more information.

4-16 Form Building and Compiling

ATTRIBUTES Section

Overview
The ATTRIBUTES section associates an identifier and a data type with every
field in the SCREEN section. You can also describe the behavior and appear-
ance of each field by using attributes to describe how INFORMIX-4GL should
display the field, specify a default value, limit the values that can be entered,
or set other parameters. Attributes are described later in this chapter, in the
section“Attributes Syntax.”

Syntax
ATTRIBUTES
field-tag = field-description ;
...
[ END ]

Explanation
ATTRIBUTES is a required keyword to mark the beginning of the
ATTRIBUTES section.
field-tag is a field tag specified in the SCREEN section.
field-description specifies a field name and optional attributes.
END is an optional keyword to mark the end of the ATTRIBUTES
section.

Notes
1. The ATTRIBUTES section must describe every field-tag from the SCREEN
section. (Tags with more than one field-description are described later in
‘‘Multiple-Column Fields.’’)
2. The order in which you list the field tags determines the order of fields 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 field not associated with any column is called a form-only field.

Form Building and Compiling 4-17

ATTRIBUTES Section

Fields Linked to Database Columns

You can specify two kinds of field descriptions: those that associate a field tag
with the data type and default display attributes of a database column, and
those that link field tags to form-only fields.
Unless a screen field is form-only, its field-description must specify the identi-
fier of some column in the database as the name of the field. Screen fields are
associated with database columns only during the compilation of the form
specification file. 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 identifies the data types
from the system catalogs, the association between the fields and database
columns is broken. INFORMIX-4GL programs must mediate between screen
fields and database columns with program variables.

Syntax
field-tag = [ table.] column [ , attr-list ] ;

Explanation
field-tag is a field tag that identifies a field in the SCREEN section.
table is a table name or alias from the TABLES section.
column 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 field.
attr-list is one or more FORM4GL field attribute specifications, separated
by commas.

Notes
1. Although you must include an ATTRIBUTES section that names every
field-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 field names collectively through
a screen record built upon all the fields related to a single table, your
forms may be easier to work with if you specify table for each field.

4-18 Form Building and Compiling

ATTRIBUTES Section

(The ‘‘INSTRUCTIONS Section’’ provides more information about screen

records.)
3. A screen field can display a portion of a character string by using sub-
scripts in the column specification. 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 file lists fields 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 ][f001 ]
Address:[f002 ][f003 ]
City:[f004 ] State:[a0] Zip Code:[f005 ]
Telephone:[f006 ]
}

TABLES customer

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 fields 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 specifies FORMONLY, this is the only kind of field description that you
can specify in the ATTRIBUTES section.

Syntax
fieldtag = FORMONLY. field-name
[ TYPE [ data-type [ NOT NULL ] | LIKE [ table. ] column ] ] [ , attr-list ] ;

Form Building and Compiling 4-19

ATTRIBUTES Section

Explanation
field-tag is the field tag used in the SCREEN section.
FORMONLY is a keyword indicating that the field does not correspond
to a column of a table in the database.
field-name is an SQL identifier for the name of the field.
TYPE is a keyword to specify an INFORMIX-4GL data type.
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.)
LIKE is a keyword to associate the screen field with the data type
specification of a database column.
table is a table alias, name, or synonym.
column is the name of a column in the database.
NOT NULL are keywords to specify that, if you reference this field in an
INFORMIX-4GL INPUT or INPUT ARRAY statement, the user
must enter a value in the field.
attr-list is a list of one or more FORM4GL display field attribute spec-
ifications, separated by commas. (See the section “Attributes
Syntax” for a list of FORM4GL attributes.)

Notes
1. You must specify a data-type only if you use the INCLUDE or DEFAULT
attribute for this field. Otherwise, FORM4GL assumes the field is a CHAR
type whose length is the width of the field. INFORMIX-4GL performs the
necessary data conversion for the corresponding program variable dur-
ing input or display.
2. When describing data-type, do not give a length to type CHAR, DECIMAL,
or MONEY fields, since the length is determined by the display width in
the SCREEN section.
3. If you specify one or more FORMONLY fields, INFORMIX-4GL behaves as
if they formed a database table named formonly, with the field 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 field in INPUT or
INPUT ARRAY statements. If you do not specify any type, INFORMIX-4GL
treats the field as type CHAR.

4-20 Form Building and Compiling

ATTRIBUTES Section

Examples
The following form-only fields could be used in an order entry form to dis-
play information about items:
f020 = formonly.manu_name;
f021 = formonly.description;
f022 = formonly.unit_price;
f023 = formonly.unit_descr;
f024 = formonly.order_placed
TYPE DATETIME YEAR TO HOUR NOT NULL, DEFAULT = CURRENT;
The demonstration application uses the following form-only field 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 fields that occupy several lines. To create a mul-
tiple-line field, repeat the same field tag in different fields of the layout in the
SCREEN section, typically on successive lines. You must also specify the
WORDWRAP attribute for that field tag in the ATTRIBUTES section. During
input and display, INFORMIX-4GL treats these fields as segments of a single
field.
The following example shows only the SCREEN and ATTRIBUTES sections of
a form specification file that specifies a multiple-line field:
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 field whose tag is synopsis appears in five physical segments
in the screen layout and has the WORDWRAP attribute, it is a multiple-line
field. Its value is composed of the physical segments taken in top-to-bottom,
left-to-right order. The field 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 field in the last line of the ATTRIBUTES section, the
keyword WORDWRAP enables a multiple-line editor. If you omit it, words
cannot flow from segment to segment of the field, and users must move the
cursor from field to field 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 fields that display data via program variables from two or
more database columns.
The database columns that you assign to the same field must have the same
field size. Usually they also have the same data type. If they are character
columns, they must have the same length. The following specification in the
ATTRIBUTES section assigns two column names to a field tag, so that the
names table1. column and table2. column both reference the same field:
field-tag = table1.column = table2.column;
You can also include one or more attribute lists in field descriptions when you
assign several columns to the same field. The placement of attributes deter-
mines when they take effect. When INFORMIX-4GL executes an INPUT,
INPUT ARRAY, DISPLAY, or DISPLAY ARRAY statement, the screen fields
listed (explicitly or implicitly) in the 4GL statement are called active fields.
If you want an attribute to apply regardless of which field name is active,
place the attribute in an attr-list after the last field name:
field-tag = table1.column = table2.column, attr-list;
If you want different attributes to apply for each of the field names, place a
semicolon ( ; ) after the attribute list for each field name:
field-tag = table1.column, attr-list1;
= table2.column, attr-list2;
Here attr-list1 is effective when table1.column is active, and attr-list2 is effec-
tive 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 field, regardless of their placement.)

4-22 Form Building and Compiling

ATTRIBUTES Section

Attributes Syntax
FORM4GL recognizes the following display field attributes:
AUTONEXT NOENTRY
COLOR PICTURE
COMMENTS REQUIRED
DEFAULT REVERSE
DISPLAY LIKE UPSHIFT
DOWNSHIFT VALIDATE LIKE
FORMAT VERIFY
INCLUDE 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 field use the following syntax format:
field-tag = [ table. ] column, attr ;
Here field-tag is a field tag that was specified in the SCREEN section, column or
table.column is the name of a screen field (either linked to a database column
or FORMONLY ), and attr specifies an attribute. This format is simplified by
ignoring multiple-column fields, and by omitting terms that specify the
data-type and NOT NULL keywords of a form-only field. Here is the complete
syntax of a field description that assigns one or more attributes.

Syntax
field-tag =
{ [ table. ] column
| FORMONLY. field-name
[ TYPE [ data-type [ NOT NULL ] | LIKE [ table. ] column ] ] }
, attr [ , attr ] [ = . . . ] [ ; ] [ = . . . ] ;
Refer to this complete syntax if you need to specify a form-only field or a mul-
tiple-column field.
Note: INFORMIX-OnLine supports an additional attribute, PROGRAM. Refer to
the INFORMIX-OnLine Programmer’s Manual for more information.

Form Building and Compiling 4-23

AUTONEXT

Overview
Use the AUTONEXT attribute to cause the cursor to advance automatically
during input to the next field when the current field is full.

Syntax
field-tag = [ table. ] column, AUTONEXT;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
AUTONEXT is a keyword that tells INFORMIX-4GL to advance the cursor
to the next field when the current field is full.

Notes
1. You specify the order of fields in each INPUT or INPUT ARRAY statement.
2. AUTONEXT is particularly useful with character fields in which the input
data are of a standard length, such as numeric postal codes, or the abbre-
viations in the state table. It is also useful if a character field has a length
of one, since only one keystroke is required to enter the data and to move
to the next field.
3. If data entered in the field does not meet requirements of other attributes
like INCLUDE or PICTURE, the cursor does not automatically move to the
next field, but remains in the current field.
4. If the most recent OPTIONS statement specifies INPUT WRAP, the ‘‘next’’
field after the last field is the first field.

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 field (thus filling
the field), the cursor moves automatically to the beginning of the next field
(the customer.zipcode field). When five characters are entered into the
customer.zipcode field (filling this field), the cursor moves automatically
to the beginning of the next field (the customer.phone field).

Form Building and Compiling 4-25

COLOR

Overview
You can use the COLOR attribute to display field text in color on color moni-
tors, or to specify other video attributes for field text.

Syntax
field-tag = [ table. ] column, COLOR = dispmode [ . . . ] [ WHERE condition ] ;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a database column
or FORMONLY).
COLOR = is a keyword, followed by an equal ( = ) sign.
dispmode is the name of a screen color or intensity.
WHERE is a keyword to specify a Boolean expression.
condition is a Boolean expression. If it is TRUE, text in the field is
displayed with the dispmode attribute.

Notes
1. The condition can be a Boolean expression of the following forms:
expr relop expr expr [ NOT ] IN (expr [ , expr . . . ] )
expr IS [ NOT ] NULL expr [ NOT ] BETWEEN expr AND expr
( bool-expr ) expr [ NOT ] LIKE expr [ ESCAPE "char"]
NOT bool-expr expr [ NOT ] MATCHES expr [ ESCAPE "char"]
bool-expr [ AND | OR ] bool-expr
for relop a relational operator ( = <> != > >= <= < ); bool-expr a Bool-
ean expression; and expr the current field-tag, a constant, or TODAY or
CURRENT, arithmetic symbols, or the unary minus symbol:
( expr ) expr { + | - | * | / } expr - expr
2. In a condition, a field tag evaluates to the current value in the field.
3. If you do not specify a condition, the intensity and/or color in your
dispmode list applies to the field.

4-26 Form Building and Compiling

COLOR

4. If condition is FALSE, the field is displayed with default characteristics,

rather than with the attribute specified 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 Text Display Intensity Text Display
WHITE White BLINK Blinking
YELLOW Yellow * UNDERLINE Underlined
MAGENTA Magenta * REVERSE Reverse (inverse) video
RED Red LEFT Left-justified
CYAN Cyan
GREEN Green
BLUE Blue * The only attributes available on systems
BLACK Black where INFORMIXTERM = terminfo

Examples
This example specifies that field text appears in red:
f000 = customer.customer_num, color = red;
The next lines specify various field displays if conditions are TRUE:
f002 = manufact.manu_code, color = red WHERE f002 = "HRO";
f003 = customer.lname, color = red WHERE f003 LIKE "Quinn";
f004 = mytab.col6, color = green WHERE f004 < 10000;
f005 = 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

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 field and is erased when
the cursor moves to another field.

Syntax
field-tag = [ table. ] column, COMMENTS = "message" ;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
COMMENTS = is a keyword, followed by an equal ( = ) sign.
message is a character string enclosed in quotation marks.

Notes
1. The message must appear between quotation ( " ) marks on a single line of
the form specification file.
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 specific
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 field 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 field description unless the message is
appropriate to all of the tasks in which the message can appear.
If the same field 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 specification file.

Example
This field description specifies a message for the Comment line. The message
will appear when the screen cursor enters the field that displays the first
name of a customer:
c2 = customer.fname, comments =
"Please enter initial if available.";

Related Attribute
INCLUDE

Form Building and Compiling 4-29

DEFAULT

Overview
Use the DEFAULT attribute to assign a default value to a display field.

Syntax
field-tag = [ table. ] column, DEFAULT = value;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
DEFAULT = is a keyword, followed by an equal ( = ) sign.
value is the default value.

Notes
1. Default values have no effect when you execute the INPUT statement
using the WITHOUT DEFAULTS option. In this case, INFORMIX-4GL dis-
plays 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 fields default
to blanks, number and INTERVAL fields to 0, and MONEY fields 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 fields 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 field. (See the syntax in the section “Form-Only
Fields” earlier in this chapter.)
5. For CHAR or DATE fields, enclose value in quotes ( " ).

4-30 Form Building and Compiling

DEFAULT

6. If the field type is DATETIME or INTERVAL, you can enclose value in quo-
tation ( " ) marks, or enter it as an unquoted literal:
DATETIME (values) qualifier
[ + | - ]INTERVAL (values) qualifier
Here values and qualifier are terms described in Appendix J. Besides these
quoted and literal formats, a value of data type INTERVAL can also be
specified in the format:
expression UNITS field
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 field is a DATETIME element name, such as
MONTH, DAY, HOUR, and so forth. (Here field is neither a field name nor
field tag.)
7. If both the DEFAULT attribute and the REQUIRED attribute are assigned to
the same field, 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 field.
9. Use the CURRENT keyword as the value to assign the current date and
time as the default for a DATETIME field.

Example
The following field 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

Overview
Use the DISPLAY LIKE attribute to display the field by using the attributes
assigned to a database column in the syscolatt table.

Syntax
field-tag = [ table. ] column, DISPLAY LIKE tbl.col;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
DISPLAY LIKE are required keywords.
tbl.col is the name of a database column.

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

Overview
Assign the DOWNSHIFT attribute to a character field when you want INFOR-
MIX-4GL to convert uppercase letters entered by the user to lowercase letters,
both on the screen and in the corresponding program variable.

Syntax
field-tag = [ table. ] column, DOWNSHIFT;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
DOWNSHIFT 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

Overview
Use the FORMAT attribute with a DECIMAL, SMALLFLOAT, FLOAT, or DATE
field to control the format of output displays.

Syntax
field-tag = [ table. ] column, FORMAT = " format-string" ;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
FORMAT = is a keyword, followed by an equal ( = ) sign.
format-string is a string of characters to specify a data format. You must
enclose format-string in quotation marks.

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, INFOR-
MIX-4GL right justifies 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
justified in the field.
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 produces the two-digit representation of the month.
mmm produces a three-letter abbreviation of the month; for exam-
ple, Jan, Feb, and so on.

4-34 Form Building and Compiling

FORMAT

dd produces the two-digit representation of the day.

ddd produces a three-letter abbreviation of the day of the week;
for example, Mon, Tue, and so on.
yy produces the two-digit representation of the year.
yyyy 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 field name of a multiple-column field, the
field uses the specified format-string regardless of which column is active.

Examples
For DATE fields:
Input Result
no FORMAT attribute 09/15/1989
FORMAT = "mm/dd/yy" 09/15/89
FORMAT = "mmm dd, yyyy" Sep 15, 1989
FORMAT = "yymmdd" 890915
FORMAT = "dd-mm-yy" 15-09-89
FORMAT = "(ddd.) mmm. dd, yyyy" (Sat.) Sep. 15, 1989

Related Attribute
PICTURE

Form Building and Compiling 4-35

INCLUDE

Overview
Use the INCLUDE attribute to specify acceptable values for a field, and to
cause INFORMIX-4GL to check before accepting an input value.

Syntax
field-tag = [ table. ] column, INCLUDE = ( { value | value TO value } [ , . . . ] );

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
INCLUDE = is a keyword, followed by an equal ( = ) sign.
value 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, sepa-
rated by commas.
TO is a keyword that separates the lower and upper limits of a
range of values.

Notes
1. If table is FORMONLY, you must specify a data type when you assign the
INCLUDE attribute to a field. (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 first.
(Here ‘‘lower’’ means the number closer to zero or with the larger nega-
tive 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 field, the range 5 TO 10 is acceptable.
In a character field, 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 field 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

Overview
Use the NOENTRY attribute to prevent data entry during an INPUT or
INPUT ARRAY statement.

Syntax
field-tag = [ table. ] column, NOENTRY;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
NOENTRY is a keyword indicating that no data can be entered in the
field by an INPUT or INPUT ARRAY statement.

Note
The NOENTRY attribute does not prevent data entry into a field 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 dur-
ing the INSERT statement. You can, however, use the same field to enter the
stock number intended for the items table.

4-38 Form Building and Compiling

PICTURE

Overview
Use the PICTURE attribute to specify the character pattern for data entry to a
character field.

Syntax
field-tag = [ table. ] column, PICTURE = "format-string";

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
PICTURE = is a keyword, followed by an equal ( = ) sign.
format-string is a string of characters (enclosed in quotes) to specify the
desired character pattern.

Notes
1. A format-string can include three special symbols:
Symbol Meaning
A Any letter
# Any digit
X 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 field and
leaves blanks elsewhere.
3. The format-string must fill the entire width of the display field.
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 field. 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 fields, 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 field
separator, produces a run-time error.

Examples
The field specification
c10 = customer.phone,
picture = "###-###-####x#####";
produces the following display field before data entry:
[ - - x ]
As another example, if you specify a field 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

Overview
Use the REQUIRED attribute to force data entry in a particular field during
an INPUT or INPUT ARRAY statement.

Syntax
field-tag = [ table. ] column, REQUIRED;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
REQUIRED is the keyword that instructs INFORMIX-4GL to insist upon
data entry to the field-tag field.

Notes
1. The REQUIRED keyword is effective only when table.column occurs in
the list of screen fields of an INPUT or INPUT ARRAY statement.
2. There is no default value for a REQUIRED field. If you assign both the
REQUIRED attribute and the DEFAULT attribute to the same field, INFOR-
MIX-4GL assumes that the DEFAULT value satisfies the REQUIRED
attribute.
3. The REQUIRED attribute requires only that the user enter a printable
character in the field. If the user subsequently erases the entry during the
same input, INFORMIX-4GL considers the REQUIRED attribute satisfied. If
you want to insist on a non-NULL entry, make the field form-only and
NOT NULL.

Example
If your ATTRIBUTES section includes the field 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

Overview
Assign the REVERSE attribute to fields that you want INFORMIX-4GL to
display in reverse video (dark characters in a bright field).

Syntax
field-tag = [ table. ] column, REVERSE;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
REVERSE is the keyword that instructs INFORMIX-4GL to display the
field-tag field in reverse video.

Notes
1. On terminals that do not support reverse video, fields having the
REVERSE attribute are enclosed in angle brackets ( < > ) .
2. If REVERSE is an attribute of any field name of a multiple-column field,
the field 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

Overview
Assign the UPSHIFT attribute to a character field when you want INFOR-
MIX-4GL to convert lowercase letters in data entry to uppercase letters, both
on the screen and in the program variable corresponding to that field.

Syntax
field-tag = [ table. ] column, UPSHIFT;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
UPSHIFT 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 que-
rying 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 field regardless of the case used to enter them.
The AUTONEXT attribute tells INFORMIX-4GL to move automatically to the
next field once you type the total number of characters allowed for the field
(in this instance, two characters). The INCLUDE attribute restricts entry in this
field to the characters CA, OR, NV, or WA only. The DEFAULT value for the field
is CA.

4-44 Form Building and Compiling

UPSHIFT

Related Attribute
DOWNSHIFT

Form Building and Compiling 4-45

VALIDATE LIKE

Overview
Use the VALIDATE LIKE attribute to cause INFORMIX-4GL to validate the
data entered into the field, using the default attributes assigned to a database
column in the syscolval table.

Syntax
field-tag = [ table. ] column, VALIDATE LIKE tbl.col;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
VALIDATE LIKE are required keywords.
tbl.col is the name of a database column

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

Overview
Use the VERIFY attribute when you want INFORMIX-4GL to require users to
enter data twice for a particular field, in order to reduce the probability of
erroneous data entry.

Syntax
field-tag = [ table. ] column, VERIFY;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a field (either related to a column or
FORMONLY).
VERIFY is the keyword that instructs INFORMIX-4GL to require
duplicate data entry to the field-tag field.

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 field and presses RETURN, INFORMIX-4GL erases the field 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 field 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

Overview
Use the WORDWRAP attribute in a multiple-line field to enable the multiline
editor. This attribute wraps a long character string to the next line of a multi-
ple-line field for data entry and display.

Syntax
field-tag = [ table. ] column, WORDWRAP [ COMPRESS ] ;

Explanation
field-tag is the field tag used in the SCREEN section.
table.column is the name of a multiple-line field (either related to a column
or FORMONLY).
WORDWRAP is a keyword to wrap long character strings to the next seg-
ment of a multiple-line field.
COMPRESS 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 field to display output, the data
is poured out into the segments of the multiple-line field, in left-to-right
and top-to-bottom order.
2. When text is entered into a multiple-line field whose attributes include
WORDWRAP, the multiline editor breaks character strings into segments
at blanks (if it can), padding field 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 fields 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

the display to the start of the next line. Tab stops are in every eighth
column, beginning at the left-hand edge of the field.
5. Ordinarily, the length of the variable should not be greater than the total
length of the field. When the data is longer than the field (or if too much
padding is required for WORDWRAP), the multiline editor fills the field
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.
6. The editor distinguishes between intentional blanks (from the database or
typed by the user) and editor blanks (inserted at the ends of lines for word-
wrap 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.
7. When designing a multiple-line field, you should allow room for editor
blanks, over and above the variable length. The expected number of edi-
tor blanks is half the length of an average word per line. Text that requires
more space than you expect might be truncated after the final line of the
field.
8. The COMPRESS keyword prevents blanks produced by the editor from
being included in the program variable. If you specify COMPRESS, trun-
cation 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.
9. If you omit COMPRESS, all blanks are retained in the variable, even editor
blanks, and the contents of a variable reflect 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 field segment
lengths exceeds the length of the variable, some trailing characters might
be truncated.
10. An earlier section, ‘‘Multiple-Line Fields,’’ describes the SCREEN section
specifications for multiple-line fields.
11. When data is entered or updated in a WORDWRAP field, 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 charac-
ter, 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 first enters a multiline field, it is positioned on the first
character of the first segment, and the mode is set to typeover. The cursor
movement keys are as follows:
RETURN leaves the entire multiline field, and goes to the first
character of the next field.
BACKSPACE moves left one character, unless at the left edge of a
or segment. From the left edge of the first segment, these
LEFT ARROW either move to the first character of the preceding field,
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.
RIGHT ARROW 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 first character of the next field, or only
beeps, depending on input wrap mode. From the right-
most intentional character of a higher segment, this
moves to the first intentional character in a lower seg-
ment.
UP ARROW moves from the topmost segment to the first character
of the preceding field. From a lower segment, this
moves to the character in the same column of the next
higher segment, jogging left, if required, to avoid edi-
tor blanks, or if it encounters a TAB.
DOWN ARROW moves from the lowest segment to the first character
of the next field. 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.
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 field
segment if required.
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 final segment of the field. The other keystrokes
that alter data are:
CONTROL-A switches between typeover and insert mode.
CONTROL-X deletes the character under the cursor, possibly caus-
ing words to be pulled up from subsequent segments.
CONTROL-D deletes all text from the cursor to the end of the multi-
ple-line field (not merely to the end of the current field
segment).
CONTROL-N inserts a NEWLINE character, causing subsequent text
to align at the first column of the next segment of the
field, and possibly moving words down to subsequent
segments. This can result in characters being discarded
from the final segment of the field.
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 field. 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 differ-
ent 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 first 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 field 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 Edi-
tor 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 specifications, a CHAR value in the column charcolm is
displayed in the multiple-line field 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 fit in the first line, successive segments will be
displayed in successive lines, until all of the lines are filled, or until the last
text character is displayed (whichever happens first).
If the form is used to insert data into tablet.charcolm, the keyword
COMPRESS specifies 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 Programmer’s Manual for more information.

INSTRUCTIONS Section
The INSTRUCTIONS section is the optional final section of a form specification
file. You can use this section to specify non-default field delimiters, and to
define screen records and screen arrays. It appears after the last field descrip-
tion (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.
delimiters specifies two non-default screen field delimiters.
record specifies a screen record.
array specifies an array of screen records.
END is an optional keyword to mark the end of the
INSTRUCTIONS section.

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 fields
when the form appears on the screen from brackets ( [ ] ) to any other print-
able character, including blank spaces.

Syntax
DELIMITERS "ab"

Explanation
DELIMITERS is a keyword to specify field delimiters.
a is the opening field delimiter.
b is the closing field delimiter.

Notes
1. The DELIMITERS instruction tells INFORMIX-4GL what symbols to use as
field delimiters when it displays the form on the screen.
2. FORM4GL requires brackets ( [ ] ) in the SCREEN section of a form
specification file, 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 fields on the same line are
ordinarily separated by at least two spaces. If you want only one space
between consecutive screen fields, follow these two steps:
(1) In the SCREEN section, substitute a vertical bar ( | ) for paired
back-to-back ( ][ ) brackets that separate adjacent fields.
(2) In the INSTRUCTIONS section, define some symbol as both the
beginning and ending delimiter. For example, you could specify
"| |" or "/ /" or ": :" or " " (blanks).

Examples
The following specifications display < and > as opening and closing delimit-
ers of screen fields:
INSTRUCTIONS
DELIMITERS "<>"
END
The following specifications substitute | for ][ between adjacent fields in the
same line of the screen layout, and display a colon ( : ) as both the opening
and closing delimiter:
SCREEN
{
. . .
Full Name-[f011 |f012 ]
. . .
}
. . .
INSTRUCTIONS
DELIMITERS "::"
Here the fields whose tags are f011 and f012 will be displayed as:
Full Name-: | :
If you substitute blanks for colons as DELIMITERS symbols, field 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 fields into screen records. Define any screen
records in the INSTRUCTIONS section of a form specification file, and refer to
them in your INFORMIX-4GL program.

Syntax
SCREEN RECORD record-name
( { table.*
| table.column1 THRU table.column2
| table.column } [ , . . . ] )

Explanation
SCREEN are keywords to define a list of fields as a screen record or
RECORD as a screen array.
record-name is an SQL identifier for the screen record.
table is a table name, alias, or synonym (or the keyword
FORMONLY).
column1, are field names that you defined in the ATTRIBUTES section.
column2, (These identifiers link the fields to database columns, unless
column you specify table as FORMONLY.)
THRU is an optional keyword to specify consecutive fields. The
keyword THROUGH is a synonym.

Notes
1. A screen record or screen array can include fields with different table
specifications, including FORMONLY.
2. FORM4GL automatically creates a default screen record for each table that
is used to identify a field in the form specification file. The default record,
which has the name of the table, contains components corresponding to
only those columns in the table that are fields on the form. The order of
components in a screen record is the order of the field names in the
ATTRIBUTES section. Use table.* to denote the same fields as the default
record for table.
3. FORM4GL returns an error if you define a screen record with the same
name as a table in the form.
4. The option of giving a range of field names with the THROUGH (or THRU)
keyword assumes the order in which the fields are listed in the
ATTRIBUTES section. The THRU keyword is shorthand for listing all fields

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 fields 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 fields 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 fields into screen arrays. A screen array is
usually an array of lines on the form, each containing identical groups of
screen fields. Each ‘‘column’’ of a screen array consists of fields with the same
tag. Define 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 specifies 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
specification file:
SCREEN
{
...
Item 1 [p ][q ][u ][t ]
Item 2 [p ][q ][u ][t ]
Item 3 [p ][q ][u ][t ]
Item 4 [p ][q ][u ][t ]
Item 5 [p ][q ][u ][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 five rows and four columns and includes fields
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 fields, corresponding to the quantity
and total_price columns of the items table.

Default Screen Attributes

As an alternative to entering attributes in the form specification file, 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 fields whose names correspond to database col-
umns. FORM4GL adds the attributes listed in these tables to attributes listed
in the form specification file. In case of conflict, attributes explicitly
mentioned in the form specification file take priority.

Form Building and Compiling 4-57

Default Screen Attributes

INFORMIX-4GL enforces the resulting set of field 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 syscolatt
tabname char(18) tabname char(18)
colname char(18) colname char(18)
attrname char(10) seqno serial
attrval char(64) 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 col-
umn. Permissible values for the attrname and attrval columns in syscolval
are shown in the following table:
attrname attrval
INCLUDE as in this chapter
PICTURE as in this chapter
DEFAULT as in this chapter
COMMENTS as in this chapter
SHIFT UP, DOWN, NO (the default)
VERIFY YES, NO (the default)
AUTONEXT 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 specified by each value of color, and the
correspondence between default color names and intensities.
Number Color Terminal Monochrome Terminal
0 White Normal
1 Yellow Bold
2 Magenta Bold
3 Red Bold†
4 Cyan Dim
5 Green Dim
6 Blue Dim†
7 Black Invisible

4-58 Form Building and Compiling

Default Screen Attributes

The background for colors is BLACK in all cases. The † signifies that, if the
keyword BOLD is indicated as the attribute, the field will be RED on a color
terminal; or, if the keyword DIM is indicated as the attribute, the field will be
BLUE on a color terminal.

You can also define non-default names for colors, by associating different
names with the color number codes in a file named colornames.
Appendix I describes the format of the colornames file. If this exists in
$INFORMIXDIR/incl (see Appendix C), INFORMIX-4GL examines
colornames at compile time to obtain the correspondence between the num-
bers 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 non-
default colors from colornames to specify the COLOR attribute in a form
specification file.)
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 charac-
ters in a dark field), 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 identified by tabname and colname is the subject of all comparisons.
Examples of permitted entries for the condition column follow:
<= 100 MATCHES "[A-M]*"
BETWEEN 101 AND 1000 IN ("CA", "OR", "WA")
>= 1001 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 BLUE = DIM
YELLOW = BOLD BLACK = INVISIBLE
MAGENTA = BOLD REVERSE
RED = BOLD BLINK
CYAN = DIM UNDERLINE
GREEN = DIM

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 file, 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 specification file, 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 field has only the BLUE attribute. You do not get blinking BLUE. As stated
earlier, form specification file 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 specifica-
tions, if these are in conflict.
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 ter-
minfo files on UNIX systems. Appendix I describes the changes that should
be made in system information files to support these display features for
your terminal. Systems that use terminfo files rather than termcap, however,
support no INFORMIX-4GL display attributes except REVERSE and UNDER-
LINE.

The upscol Tables in a MODE ANSI Database

In a database that is not MODE ANSI, the default screen attributes and valida-
tion 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 specifications of that individual
user. Which set of upscol tables is used by FORM4GL depends on the nature
of the request.
If the TABLES section specifies 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 fields 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 fields associated with that database table, unless the user owns no
upscol tables.
In the ATTRIBUTES section, specifications of the form
field-tag = . . . DISPLAY LIKE table.column

field-tag = . . . VALIDATE LIKE table.column

use upscol tables (if they exist) owned by the user who runs FORM4GL,
unless table is an alias that specifies a different owner. If table is an alias for
owner.table, FORM4GL uses the upscol tables of the owner specified 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 specification file and its customized screen form either
through the INFORMIX-4GL Programmer’s 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 subsec-
tions describe these alternative procedures.

Form Building and Compiling 4-61

Through the Programmer’s Environment

To create a screen form using the Programmer’s 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 specification file. Now you must
enter form specifications. The Generate option is usually a more efficient
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 specification file, as well as a
compiled default form, and then displays the FORM Design Menu.
4. The default form specification file 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 specification (given as myform
earlier), and INFORMIX-4GL calls a system editor to display the file. Edit
the default form specification file 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 file and quit the editor, you return to the
MODIFY FORM Menu.
5. Select Compile. If your form specification file successfully compiles,
FORM4GL creates a form file with the extension .frm (for example,
myform.frm). Go on to Step 7. If your form specification file 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 specification file, with the com-
pilation errors marked. When correcting your errors, you need not delete
the error messages. INFORMIX-4GL does that for you. Save the file and go
to Step 5.
7. Save your form specification file with the Save-and-exit option.

4-62 Form Building and Compiling

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.)
-c cols 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 specified in the SCREEN
section.)
-v are optional characters to verify that the screen fields are as
wide as any corresponding character fields specified in the
ATTRIBUTES section.
form-name is the name of the form specification file (without the .per
extension).
-d are optional symbols to specify a default form specification file.
To create a customized screen form directly from the operating system,
follow these steps:
1. Create a default form specification file by entering the command
form4gl -d
at the operating system prompt. FORM4GL asks for the name of your
form specification file, 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 specification file 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 specification file to meet
your specifications. If, as an alternative, you create a new form specifica-
tion file and skip Step 1, be sure to give the filename 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 specification file (without the .per
extension).
If the compilation is successful, FORM4GL creates a compiled form file
called myform.frm and you are finished creating your customized screen
form. If not, FORM4GL instead creates a file named myform.err, and you
need to go on to Step 4.
4. Review the file myform.err to discover the compilation errors. Make
corrections in the file 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 specification 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 fields that
correspond to columns in different tables.
• Joins defined in the PERFORM form specification are ignored in INFOR-
MIX-4GL. You can associate two field names with the same field 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 field 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

5
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 37
NEED 38
PAUSE 39
PRINT 40
PRINT FILE 42
SKIP 43
Expressions and Built-in Functions 44
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
first-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 INFOR-
MIX-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 exam-
ples of REPORT routines.)

Report Writing 5-3

Calling a REPORT Routine

To call a REPORT routine requires three 4GL statements that occur before,
during, and after a program loop that you define. 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 defined outside the MAIN program
block
START REPORT report-name
[ TO { PRINTER | PIPE program | filename } ]

OUTPUT TO REPORT report-name ( variable-list )

FINISH REPORT report-name

The basic loop structure (whether a FOR, FOREACH, or WHILE loop) is illus-
trated 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
specifies the output file 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 find the full syntax for these statements in Chapter 7.

5-4 Report Writing

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 file.
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 specifies a non-default page
length and margins for the physical format of the report, and specifies
whether INFORMIX-4GL sends the report to the screen, to a file, or to
another program.
• ORDER BY Section: This optional section specifies 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 specifies 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 specific
groups of rows are processed, using any INFORMIX-4GL statement,
expression, or function. Control blocks can also include certain state-
ments 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 first 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.
report-name is an INFORMIX-4GL identifier.
(argument-list) is a list of variables or record identifiers, enclosed in paren-
theses and separated by commas.
END REPORT are required keywords.

Notes
1. Record identifiers 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.
variable-list is one or more identifiers of program variable.
type is one of these data types (as defined in Chapter 2):
SMALLINT MONEY [ (m [ , n ] ) ]

INTEGER CHAR [ ( n ) ]
INT CHARACTER [ (n ) ]

DECIMAL [ (m [ , n ] ) ] DATE
DEC [ ( m [ , n ] ) ]
NUMERIC [ (m [ , n ] ) ] DATETIME qualifier

SMALLFLOAT INTERVAL qualifier

REAL
RECORD [ LIKE table. * ]
FLOAT [ ( n ) ]
DOUBLE PRECISION [ ( n ) ]
LIKE is a keyword to specify the data type indirectly.
table.column is the full identifier for a column in the current database. The
DATABASE statement must precede DEFINE statements that
use indirect typing.
RECORD is a data type that describes a set of variables of possibly
differing database data types.
table is the name of a database table.
END RECORD are keywords that follow the declaration of the last element
of a program 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 identifiers 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 INFOR-
MIX-OnLine Programmer’s 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 file, 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 specifies where to send output from the report
routine. If you omit this section, output is to the screen.
• The LEFT MARGIN statement specifies how many blank spaces to include
at the left of each line of output. The default is 5 spaces.
• The RIGHT MARGIN statement specifies the maximum number of charac-
ters in each line of output, including the left margin. The default is 132
characters.
• The TOP MARGIN statement specifies how many blank lines appear
before the first line on each page of output. The default is 3 lines.
• The BOTTOM MARGIN statement specifies how many blank lines follow
the last line on each page of output. The default is 3 lines.
• The PAGE LENGTH statement specifies 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 define in the FORMAT section.
The default is 66 lines.
The pages that follow describe these OUTPUT statements.

Report Writing 5-9

REPORT TO

Overview
This optional statement directs the output of the INFORMIX-4GL report to a
file, an operating system pipe, or the system printer.

Syntax
REPORT TO { "filename" | PIPE "program" | PRINTER }

Explanation
REPORT TO are required keywords.
filename is a quoted string containing the name of a file to receive the
report.
PIPE is an optional keyword.
program 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 associ-
ated arguments, must be enclosed within quotation ( " )
marks.
PRINTER is an optional keyword.

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 file, pipe, or printer, INFORMIX-4GL ignores the REPORT TO
statement of the OUTPUT section.
3. If filename 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 filename option to send output to a file, and
then send the file 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 file.
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

Overview
This statement sets a left margin for a report.

Syntax
LEFT MARGIN integer

Explanation
LEFT MARGIN are required keywords.
integer is an integer that specifies the width of the left margin, in
spaces.

Notes
1. The default left margin is five 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

Overview
This statement sets a right margin for a report.

Syntax
RIGHT MARGIN integer

Explanation
RIGHT MARGIN are required keywords.
integer is an integer that specifies the width of the text on the
page, in characters.

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 col-
umns beneath these headings. If there is not sufficient room between the
LEFT MARGIN and the RIGHT MARGIN to do this, INFORMIX-4GL pro-
duces 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 state-
ment. 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

Overview
This statement sets a top margin for a report.

Syntax
TOP MARGIN integer

Explanation
TOP MARGIN are required keywords.
integer is an integer that specifies the number of blank lines that
INFORMIX-4GL leaves at the top of each page.

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

Overview
This statement sets a bottom margin for a report.

Syntax
BOTTOM MARGIN integer

Explanation
BOTTOM MARGIN are required keywords.
integer is an integer that specifies the number of blank lines
that INFORMIX-4GL is to leave at the bottom of each
page.

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

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 specifies 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 specifies 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 specifies 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 are required keywords.
EXTERNAL is an optional keyword.
sort-list is a list of one or more variables from the list of arguments to
the REPORT routine.

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 specifies two things. First, it specifies 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 first 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 specifies the order in which INFOR-
MIX-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 specifies 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, INFOR-

MIX-4GL makes two passes through the input data. During the first pass,
it sorts the data and stores it in a temporary file. 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 con-
tain 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

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 fit on a line, INFORMIX-4GL pro-
duces 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 specification.

customer.customer_num 101
customer.fname Ludwig
customer.lname Pauli
customer.company All Sports Supplies
customer.address1 213 Erstwild Court
customer.address2
customer.city Sunnyvale
customer.state CA
customer.zipcode 94086
customer.phone 408-789-8075

customer.customer_num 102
customer.fname Carole
customer.lname Sadler
customer.company Sports Spot
customer.address1 785 Geary St
customer.address2
customer.city San Francisco
customer.state CA
customer.zipcode 94117
customer.phone 415-822-1289

. . .

INFORMIX-4GL prints only the column name when the column contains a
NULL value.

Following is another example of a brief report specification 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 104 01/20/1989

1002 101 06/01/1989
1003 104 10/12/1989
1004 106 04/12/1989
1005 116 12/04/1989
1006 112 09/19/1989
1007 117 03/25/1989
1008 110 11/17/1989
1009 111 02/14/1989
1010 115 05/29/1989
1011 104 03/23/1989
1012 117 06/05/1989
1013 104 09/01/1989
1014 106 05/01/1989
1015 110 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 first 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
Figure 5-1 Order of Group Processing

The pages that follow describe these control blocks in alphabetical order.

5-24 Report Writing

AFTER GROUP OF

Overview
The AFTER GROUP OF control block specifies 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.
variable-name is the name of one of the variables passed as an
argument.
statement is a FORMAT or INFORMIX-4GL 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 first by the first variable that you
specify (most significant). Rows having the same value on the first vari-
able 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 significant) variable that you specify.
INFORMIX-4GL processes the statements in an AFTER GROUP OF control
block each time the specified column changes value, each time a more
significant 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
significant.
5. When INFORMIX-4GL finishes 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

Overview
The BEFORE GROUP OF control block specifies 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.
variable-name is the name of one of the variables passed as an
argument.
statement is an INFORMIX-4GL or FORMAT 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 vari-
able. INFORMIX-4GL automatically groups rows when you use an ORDER
BY section of a REPORT routine or the ORDER clause of a SELECT state-
ment. 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 first by the first variable that you
specify (most significant), second by the second variable, and so on, until
the last variable that you specify (least significant) is ordered.
INFORMIX-4GL processes the statements in a BEFORE GROUP OF control
block at the start of a report, each time the specified variable changes
value, and each time a more significant 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
significant.
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 first row of the
new group. From this perspective, the BEFORE GROUP OF control block
could be called the ‘‘on first row of group’’ control block.

Example
BEFORE GROUP OF r.customer_num
SKIP TO TOP OF PAGE

5-28 Report Writing

FIRST PAGE HEADER

Overview
The FIRST PAGE HEADER control block can specify what information appears
at the top of the first page of the report.

Syntax
FIRST PAGE HEADER
statement
...

Explanation
FIRST PAGE HEADER are required keywords.
statement is an INFORMIX-4GL or FORMAT 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 first 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 filename statement to read and display text from
a file 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 INFOR-
MIX-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

Overview
The ON EVERY ROW control block specifies the action to be taken by INFOR-
MIX-4GL for every row of data that you pass to the routine.

Syntax
ON EVERY ROW
statement
...

Explanation
ON EVERY ROW are required keywords.
statement is an INFORMIX-4GL or FORMAT 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 significance) 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 significance) 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

Overview
The ON LAST ROW control block specifies 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 final 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

Overview
The PAGE HEADER control block specifies 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 first 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 filename statement to read and display text
from a file 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

Overview
The PAGE TRAILER control block specifies 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 follow-
ing 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 filename statement to read and display text
from a file 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
specified in the DEFINE section of the REPORT routine.)

Statements Valid Only in the FORMAT Section

There are five statements that you can only use in the FORMAT section of a
REPORT routine:
NEED PRINT FILE
PAUSE SKIP
PRINT
Descriptions of these FORMAT section statements follow.

Report Writing 5-37

NEED

Overview
This statement causes subsequent display to start on the next page if there is
not the specified number of lines remaining on the current page.

Syntax
NEED num-expr LINES

Explanation
NEED is a required keyword.
num-expr is an expression that evaluates to an integer specifying the
number of lines needed.
LINES is a required keyword.

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 num-
ber 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

Overview
This statement causes output to the terminal to pause until the user presses
RETURN.

Syntax
PAUSE [ "string" ]

Explanation
PAUSE is a required keyword.
string is a quoted message that PAUSE displays. If you do not supply a
message, PAUSE displays no message.

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

Overview
This statement displays information, as specified in the OUTPUT section.

Syntax
PRINT [ exprlist ] [ ; ]

Explanation
PRINT is a required keyword.
exprlist 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.

Notes
1. One PRINT statement displays its output on one line, no matter how
many lines the statement occupies in the report specification, unless the
exprlist includes the WORDWRAP function.
2. When a PRINT statement specifies 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

Data Type Default Size (in characters)

CHAR declared size
DATE 10
DATETIME depends on declared precision
INTERVAL depends on declared precision (including sign)
FLOAT 14 (including sign and decimal point)
SMALLINT 6 (including sign)
INTEGER 11 (including sign)
SMALLFLOAT 14 (including sign and decimal point)
DECIMAL number of digits plus 2 (including sign and decimal point)
SERIAL 11
MONEY number of digits plus 3 (including sign, decimal point,
and currency symbol)
Figure 5-2 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

Overview
This statement displays the contents of a text file in a report.

Syntax
PRINT FILE "filename"

Explanation
PRINT FILE are required keywords.
filename is a required filename that can be a pathname. You must enclose
filename in quotation ( " ) marks.

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

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.
integer is an integer specifying the number of lines to skip.
LINES is an optional keyword. You can use the keyword LINE in
place of LINES if you like.
TO TOP OF PAGE are optional keywords.

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 expres-
sions 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 rou-
tine. (The letter superscripts indicate where their descriptions appear in this
manual.)
ASCIIa MIN()rs
AVG()rs MDY()a
CLIPPEDa MONTH()a
COLUMNa PAGENOr
COUNT(*)rs PERCENT(*)rs
CURRENTa SPACESr
DATEa SUM()rs
DATE()a TIMEa
DAY()a TODAYa
EXTEND()a UNITSa
GROUPr USINGa
LENGTH()a WEEKDAY()a
LINENOr WORDWRAPr
MAX()rs YEAR()a
r
You can use these functions only within the FORMAT section of a
REPORT routine. A description of these functions follows.
rs
You can use these functions only within the FORMAT section of a
REPORT routine or in INSERT, SELECT, or UPDATE statements else-
where. They are described both in the following pages and in
Chapter 7.
a
These functions are described in Chapter 2.

Report Writing 5-45

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 reflect
information for a specific group only. You can only use this
keyword in an AFTER GROUP OF control block.
COUNT ( * ) is a keyword. This keyword is always evaluated as the total
number of rows qualified by the optional WHERE clause.
PERCENT ( * ) is the keyword that evaluates COUNT as a percent of the total
number of rows in the report.
SUM evaluates as the total of expr1 in the rows qualified 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.
AVG evaluates as the average of expr1 in the rows qualified 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.
MIN evaluates as the minimum of expr1 in the rows qualified 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.
MAX evaluates as the maximum of expr1 in the rows qualified 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.
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.

5-46 Report Writing

Aggregates

WHERE is an optional keyword.

expr2 is a Boolean expression that qualifies the aggregate.

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 specified, GROUP SUM combines the total_price of

every item in the group comprising the order.

Report Writing 5-47

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

Overview
This expression has the value of the page number of the page that INFOR-
MIX-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

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

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 fit 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 is an expression whose value is a character string.
WORDWRAP is a keyword to display long character strings on multiple
lines of a report.
RIGHT are optional keywords to specify a temporary right margin.
MARGIN
col is an integer expression, specifying the column number of
the temporary right margin.

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 specified or default right margin, until all of char-expr has
been included in the report.
3. If you do not specify RIGHT MARGIN, the specified 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 fit 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 fit on a line, INFORMIX-4GL
prints enough of the spaces to fill 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 mar-
gin, 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 specifies 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 fit in the first 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 INFOR-
MIX-OnLine Programmer’s Manual for more information

5-52 Report Writing

Chapter

4GL Function
Library
Chapter Overview 3
The 4GL Library Functions 3
ARG_VAL 4
ARR_COUNT 6
ARR_CURR 7
DOWNSHIFT 9
ERR_GET 10
ERR_PRINT 11
ERR_QUIT 12
ERRORLOG 13

6
INFIELD 14
LENGTH 16
NUM_ARGS 17
SCR_LINE 18
SET_COUNT 20
SHOWHELP 21
STARTLOG 23
UPSHIFT 25
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 final 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 Returned Value or Effect
arg_val Command-line argument(s)
arr_count Total filled rows of program array
arr_curr Number of the current row within program array
downshift Lowers case of uppercase letters in string argument
err_get Current 4GL error message
err_print * Prints a 4GL error message on the Error line
err_quit * Prints a 4GL error message and exits
errorlog * Appends argument to the error log
infield TRUE if argument is the name of the current field
length Length in bytes of string argument
num_args Number of command-line arguments
scr_line Number of the current row within screen array
set_count * Sets number of rows of program array
showhelp * Displays the 4GL HELP Menu and a help message
startlog * Opens an error log file
upshift 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 user-
names 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 Value
args[1] joe
args[2] bob
args[3] sue
args[4] les

Related Function
NUM_ARGS

4GL Function Library 6-5

ARR_COUNT

Overview
The arr_count function returns the number of rows that are entered in a pro-
gram 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

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 immedi-
ately 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 begin-
ning of a BEFORE ROW or AFTER ROW clause.
2. The arr_curr function returns an integer value. The first 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 cus-
tomer is not from California. (See also the definition 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

Overview
The downshift function returns a string value in which all uppercase charac-
ters 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 field 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 vari-
able called d_str:
LET d_str = downshift(p_string)

Related Function
UPSHIFT

4GL Function Library 6-9

ERR_GET

Overview
The err_get function returns a CHAR string that is the 4GL error message cor-
responding 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

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 pro-
gram. 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

Overview
The err_quit function prints on the Error line the INFORMIX-4GL error mes-
sage specified by its argument, and then terminates the program.

Syntax
CALL err_quit ( expr )

Explanation
CALL is a required keyword.
expr is an integer expression.

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

Overview
The errorlog function writes its argument in the current error log file.

Syntax
CALL errorlog ( str )

Explanation
CALL is a required keyword.
str is a string constant or a CHAR variable.

Notes
1. The error log file 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

Overview
The infield function tests whether its argument is the identifier of the current
screen field.

Syntax
infield ( field-name )

Explanation
field-name is the name of a screen field.

Notes
1. The infield function is a Boolean function that returns the value true if
field-name is the name of the current screen field. Otherwise infield
returns the value false. (The “ATTRIBUTES Section” in Chapter 4
describes how to assign a field-name to a display field of a screen form.)
2. You can use infield during an INPUT or INPUT ARRAY statement to take
field-dependent actions.
3. Outside of an INPUT or INPUT ARRAY statement, infield returns a true
or false value, based on whether field-name corresponds to the screen
field that was current when the user terminated the most recent INPUT
or INPUT ARRAY statement. Be sure to specify the field-name, not the
field tag.
4. If the current field is a multiple-column field, infield returns true only if
field-name is the active name.

6-14 4GL Function Library

INFIELD

Example
The following INPUT statement uses infield with showhelp to give field-
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
SCR_LINE

4GL Function Library 6-15

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 INFOR-
MIX-OnLine Programmer’s Manual for more information.

6-16 4GL Function Library

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 com-
mand-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 (C Compiler Version)
fglgo myprog kim sue joe (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

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 begin-
ning of a BEFORE ROW or AFTER ROW clause.
2. The first row of both the program array and of the screen array is num-
bered 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 cus-
tomer is not from Alaska. (See also the definition of the arr_curr library func-
tion 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

Overview
The set_count function tells INFORMIX-4GL the number of filled rows in a
program array.

Syntax
CALL set_count ( expr )

Explanation
CALL is a required keyword.
expr is an integer expression.

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 specifies the total number of filled rows in the program array. This func-
tion 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

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.
expr is an integer expression.

Notes
1. When called with an argument that is the number of a help message in the
help file 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 fit 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 file, 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 infield with showhelp to display field-depen-
dent 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

Overview
The startlog function opens an error log file.

Syntax
CALL startlog ( filename )

Explanation
CALL is a required keyword.
filename is a quoted string or a CHAR variable that evaluates to the name
(or the pathname) of the error log file.

Notes
1. If filename does not exist, startlog creates it. If the file exists, startlog opens
it, and positions the file pointer so that subsequent error messages are
appended to it.
2. If you do not want the error log file 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 file.
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 file by using the
errorlog function.

4GL Function Library 6-23

STARTLOG

Example
In the following example, a CALL statement invokes the startlog library func-
tion, specifying the name of the error log file in a quoted string that includes
a pathname and file 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

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 field attribute in Chapter 4.

Example
Here the CHAR variables u_str and str are equivalent, except that u_str sub-
stitutes 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
Definition of Statements 11
ALTER INDEX 12
ALTER TABLE ( O ) 14
BEGIN WORK 18

7
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 ) 41
CREATE INDEX 44
CREATE SYNONYM 47
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 190
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 228
Join Conditions 234
Subquery 237
GROUP BY Clause 240
HAVING Clause 242
ORDER BY Clause 243
INTO TEMP Clause 245
UNION Operator 246

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 REPORT
MAIN
• Variable Definition Statements
DEFINE GLOBALS
• Assignment Statements
INITIALIZE LET
• Program Flow Statements
CALL IF
CASE LABEL
CONTINUE RETURN
DEFER RUN
EXIT SLEEP
FOR WHENEVER
FOREACH WHILE
GOTO
• Screen Interaction Statements
CLEAR INPUT
CLOSE FORM INPUT ARRAY
CLOSE WINDOW MENU
CONSTRUCT MESSAGE
CURRENT WINDOW OPEN FORM
DISPLAY OPEN WINDOW
DISPLAY ARRAY OPTIONS
DISPLAY FORM PROMPT
ERROR SCROLL
• Report Generation Statements
FINISH REPORT START REPORT
OUTPUT TO REPORT

INFORMIX-4GL Statement Syntax 7-5

Statements Supported Only on INFORMIX-SE

• Data Definition Statements

ALTER INDEX DROP DATABASE
ALTER TABLE DROP INDEX
CLOSE DATABASE DROP SYNONYM
CREATE DATABASE DROP TABLE
CREATE INDEX DROP VIEW
CREATE SYNONYM RENAME COLUMN
CREATE TABLE RENAME TABLE
CREATE VIEW SET EXPLAIN
DATABASE UPDATE STATISTICS
• Data Manipulation Statements
DELETE SELECT
INSERT UNLOAD
LOAD UPDATE
• Cursor Manipulation Statements
CLOSE OPEN
DECLARE PUT
FETCH SET EXPLAIN
FLUSH
• Dynamic Management Statements
EXECUTE PREPARE
FREE
• Data Access Statements
GRANT SET LOCK MODE
LOCK TABLE UNLOCK TABLE
REVOKE
• Data Integrity Statements
BEGIN WORK ROLLBACK WORK
COMMIT WORK ROLLFORWARD DATABASE
CREATE AUDIT START DATABASE
DROP AUDIT VALIDATE
RECOVER TABLE

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 Programmer’s Manual for
details of the additional functionality available with INFORMIX-OnLine.
INFORMIX-4GL statements that support INFORMIX-OnLine enhancements
are listed here. They are identified 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 envi-
ronment variable or use the -ansi flag when you compile your 4GL source-
code files at the system prompt.
Examples:
c4gl -ansi file.4gl -o program.4ge (C Compiler Version)
fglpc -ansi file.4gl (Rapid Development System)
When you compile with the -ansi flag or with the DBANSIWARN environ-
ment variable set, SQL statements that include Informix extensions to ANSI
syntax cause warning messages to be written to the .err file. (See Appendix C
for more information about DBANSIWARN.)
Note: You cannot use the -ansi flag 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 FLUSH
ALTER TABLE FREE
BEGIN WORK GRANT
CLOSE DATABASE LOAD
CREATE AUDIT LOCK TABLE
CREATE DATABASE PUT
CREATE INDEX RECOVER TABLE
CREATE SYNONYM RENAME COLUMN
CREATE TABLE RENAME TABLE
CREATE VIEW REVOKE
DATABASE ROLLFORWARD DATABASE
DROP AUDIT SET EXPLAIN
DROP DATABASE SET LOCK MODE
DROP INDEX START DATABASE
DROP SYNONYM UNLOAD
DROP TABLE UNLOCK TABLE
DROP VIEW 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 exten-
sions to ANSI standard syntax. A warning is generated if you include these
keywords or features in an SQL statement, and then initiate Informix exten-
sion checking with the -ansi flag 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 Programmer’s Manual for more information.

7-10 INFORMIX-4GL Statement Syntax

Definition of Statements

Definition of Statements
The following section describes the INFORMIX-4GL statements. The state-
ments 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

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.
index-name is the identifier of an existing index.
TO is a required keyword.
NOT is an optional keyword.
CLUSTER is a required keyword.

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 file to be rewritten. This process may take a long time and
requires sufficient 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 assign-
ing 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 exe-
cute 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 benefit 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 )

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.
table-name is the name of an existing table.
ADD is a keyword you use to add a column.
newcol-name is the name of the column you want to add.
newcol-type is either the data type of the column you are adding or the
data type of the column you are modifying.
NOT NULL are optional keywords.
UNIQUE is a keyword specifying that the column or composite col-
umn list accepts only unique values.
CONSTRAINT is a keyword you use to indicate that constr-name is
assigned in the statement.
constr-name is the name of the constraint.
BEFORE 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.
oldcol-name is the name of an existing column.
DROP is a keyword you use to drop a column.

7-14 INFORMIX-4GL Statement Syntax

ALTER TABLE ( O )

MODIFY is a keyword you use to change the data type of an exist-

ing column.
ADD are keywords you use to place a constraint on a column or
CONSTRAINT composite column list.
DROP are keywords you use to drop a UNIQUE CONSTRAINT on
CONSTRAINT a table column.

Notes
1. In a MODE ANSI database, the name of a table is qualified 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 prefix 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
specified. 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 col-
umn 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 filled 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 specified when the con-
straint 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 per-
mission 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 first 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 con-
tains statements affecting a large number of rows, may exceed the limits
placed by your operating system on the maximum number of simulta-
neous locks. If you encounter this error, you may need to lock the entire
table immediately after beginning the transaction. See the section “Lock-
ing” in Chapter 3 for a more detailed description of table-level and row-
level 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 data-
base, the BEGIN WORK statement generates a run-time error unless it
appears immediately after one of the following statements:
CREATE DATABASE COMMIT WORK
DATABASE ROLLBACK WORK
START DATABASE
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

Overview
Use the CALL statement to invoke a function.

Syntax
CALL function ( [ argument-list ] ) [ RETURNING variable-list ]

Explanation
CALL is a required keyword.
function is the name of a function.
argument-list 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.
RETURNING is an optional keyword to specify variables that the function
will return to the calling routine.
variable-list is a list of one or more program variables, separated by
commas.

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 specified in argument-list will be passed by value.
3. You can define INFORMIX-4GL functions in the same source file 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

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.
expr is an expression that returns an INTEGER, SMALLINT,
DECIMAL, or CHAR(1) value.
WHEN is a required keyword.
Boolean-expr is an expression that is either TRUE or FALSE.
statement is an INFORMIX-4GL statement.
EXIT CASE is an optional statement that causes program control to pass
to the statement following the END CASE keywords.
OTHERWISE is an optional keyword introducing a sequence of statements
to be executed if none of the WHEN clauses is executed.
END CASE are required keywords that terminate the CASE statement.

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

Overview
Use the CLEAR statement to clear the whole screen, a window, all fields in a
screen form, or a set of fields.

Syntax
CLEAR { SCREEN | WINDOW window-name | FORM | field-list }

Explanation
CLEAR is a required keyword.
SCREEN is the keyword to clear the whole screen.
WINDOW is the keyword to clear a window.
window-name is the name of the window that you want to clear, or the key-
word SCREEN.
FORM is the keyword to clear the values in all screen fields of a
form.
field-list is a list of one or more names of fields to be cleared.

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 specified window, retaining
any border. (The specified 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 state-
ment, INFORMIX-4GL clears the screen, except for the area occupied by
any open windows.
5. CLEAR FORM and CLEAR field-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

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 flush the insert buffer and close an
INSERT cursor.

Syntax
CLOSE cursor-name

Explanation
CLOSE is a required keyword.
cursor-name is the name of a cursor that has been DECLAREd for a SELECT
or INSERT statement.

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 undefined.
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 state-
ment flushes 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.SQL-
CODE ) 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 (specifically, 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

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

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

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.
form-name is an INFORMIX-4GL identifier that you assigned to a screen
form in an OPEN FORM statement.

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 first 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 specified
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

Overview
Use the CLOSE WINDOW statement to close a window.

Syntax
CLOSE WINDOW window-name

Explanation
CLOSE WINDOW are required keywords.
window-name is the name of the window to be closed.

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, INFOR-
MIX-4GL simply removes the window from the stack, leaving the current
window unchanged. In both cases, INFORMIX-4GL restores the underly-
ing display.
3. If you close a window that is currently being used for input, INFOR-
MIX-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

Overview
Use the COMMIT WORK statement to commit all modifications 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 satisfied with all
changes made during the transaction to the database. Use the ROLLBACK
WORK statement if you do not want to commit modifications made dur-
ing 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

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-specified selection criteria.

Syntax
CONSTRUCT
{ BY NAME char-variable ON column-list |
char-variable ON column-list FROM
{ field-list | screen-record [ [ n ] ].* } [ , . . . ] }
[ ATTRIBUTE ( attribute-list) ]

Explanation
CONSTRUCT is a required keyword.
BY NAME are keywords instructing INFORMIX-4GL to match names of
database columns to screen field names.
char-variable is an identifier of a CHAR type program variable (to contain
the selection criteria).
ON is a required keyword to specify database columns.
column-list is a list of one or more database column names, separated by
commas. You can use the syntax table.*.
FROM is a keyword to specify screen fields for user entry of search
values, and for display of query results.
field-list is a list of one or more screen field names.
screen-record is the identifier of a collection of field names defined in a
form specification as a screen record.
[n] is an integer or integer variable, enclosed in brackets, to
specify the row in a screen array in which the CONSTRUCT
takes place.
ATTRIBUTE is a keyword to specify screen display attributes.
(attribute-list) is a list (in parentheses) of one or more screen display
attributes, separated by commas.

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 Data Types Pattern
= equal to all =x
> greater than all >x
< less than all <x
>= greater than or equal to all >=x
<= less than or equal to all <=x
<> not equal to all <>x
: range all x:y
.. range DATETIME x..y
and
INTERVAL
* wildcard for any string CHAR *x, x*, *x*
? single-character wildcard CHAR ?x, x?, ?x?, x??
| or all a|b...
Explanation of Symbols
• The equal sign ( = ) is the default query symbol for non-character col-
umns, 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 con-
tains a NULL column. Enter = * to find a row that contains a column
with only an asterisk.
• The x means any value of the appropriate data type for the search field.
Enter the value immediately after any one of the first six query sym-
bols 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 col-
umn. 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 find
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 field separator in hh:mi:ss values.
• Asterisk ( * ) is the string wildcard, representing zero or more charac-
ters. An *ts* search value in the field corresponding to the lname
column of the customer table would find two names, Watson and
Albertson. An S* search value in the same field would find Sadler and
Sipes. An *er search value would find the four names Sadler, Miller,
Jaeger, and Baxter.
• The question mark ( ? ) is the single-character wildcard. The user can
use the question mark to find values that match a pattern where the
number of characters is fixed. 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,’’ ‘‘New-
man,’’ and ‘‘Newson.’’
• The symbo| between values a and b means the logical OR. In the field
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 field 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 fields explic-
itly in field-list.
3. The CONSTRUCT statement is terminated when the user enters ESC or the
key specified 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 CON-
STRUCTs, 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_flag to nonzero and terminates the CONSTRUCT state-
ment (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 toggles between insert and typeover mode.
CTRL-D deletes characters from the current cursor position to the end
of the field.
CTRL-H moves the cursor nondestructively one space to the left
inside a field. It is equivalent to pressing the [←] key.
CTRL-L moves the cursor nondestructively one space to the right
inside a field. It is equivalent to pressing the [→] key.
CTRL-R redisplays the screen.
CTRL-X deletes the character beneath the cursor.
6. The user can query for only those fields displayed on the screen that you
have specified in the FROM clause or implied in the BY NAME clause. The
number of fields in the FROM clause must be the same as the number of
columns in the ON clause. The order of fields 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 field 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 field 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 field names in a screen array, the construct takes place in the first row
of the screen array.
If you want to use screen-array field names in the FROM clause of a
CONSTRUCT statement, then you must use the notation screen-record [n ].
field-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 col-
umn names include an owner name. You must use the FROM clause to
specify table aliases in the field-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 fields implied in the screen-record.* notation cor-
responds to the order of the columns implied in the screen-record.*
notation. The order of the fields in screen-record.* depends on its definition
in the screen form.
The order of the columns in table.* depends on the order in the syscol-
umns 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 pro-
gram and the forms that depend on it.
12. Any screen attributes specified in attribute-list apply to all the fields in
field-list or screen-record.
13. If you use the ATTRIBUTE clause, none of the default attributes listed in
syscolatt or in the form specification file for fields in field-list or screen-
record apply. The attribute-list temporarily overrides any attributes speci-
fied in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for
these fields.
14. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
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 inter-
preted 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 files and the physical terminals support the attribute. (See
Appendix I, “Modifying termcap and terminfo.”’)
15. On UNIX systems that use terminfo files rather than termcap, INFOR-
MIX-4GL does not support attributes that specify colors, and the only
valid attribute-list keywords are REVERSE and UNDERLINE.
16. You must first 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 state-
ment 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

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 is a required keyword.
FOR is a required keyword in a FOR statement.
FOREACH is a required keyword in a FOREACH statement.
MENU is a required keyword in a MENU statement.
WHILE is a required keyword in a WHILE statement.

Related Statements
END, EXIT

7-38 INFORMIX-4GL Statement Syntax

CREATE AUDIT

Overview
Use the CREATE AUDIT statement to create an audit trail file, and to start writ-
ing the audit trail.

Syntax
CREATE AUDIT FOR table-name IN "pathname"

Explanation
CREATE are required keywords.
AUDIT FOR
table-name is the name of the table for which to create an audit trail file.
IN is a required keyword.
pathname is the full pathname for the audit trail file. It must be
enclosed in quotation ( " ) marks.

Notes
1. You create audit trails to keep a record of all modifications 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 file with the same pathname already exists for the same
table, the CREATE AUDIT statement does nothing. If an audit trail file for
the same table exists with a different pathname, INFORMIX-4GL displays
an error message.
3. Make a backup copy of your database files as soon as you run the CREATE
AUDIT statement, but before you make any further changes to the data-
base. (See the RECOVER TABLE statement for an example.) If possible,
put the audit trail file 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 file, as well as in the database files.
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, owner’s group, and public) that accesses
your database.
7. You cannot create an audit file 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 )

Overview
Use the CREATE DATABASE statement to create a new database. INFOR-
MIX-4GL will create the system catalogs that will contain the data dictionary
describing the structure of the database. The database that you create auto-
matically becomes the current database.

Syntax
CREATE DATABASE database-name
[ WITH LOG IN "pathname" [ MODE ANSI ] ]

Explanation
CREATE are required keywords.
DATABASE
database-name is the name that you assign to the database. The database-
name can be a program variable of type CHAR containing the
name of the database you want to create.
WITH LOG IN are optional keywords to support transactions.
pathname is the full pathname, enclosed in quotation ( " ) marks, of the
transaction log file.
MODE ANSI are optional keywords that specify the database as 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 files
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 let-
ters, digits, and underscores ( _ ). The first 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 data-
base-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 file. Without this file,
you cannot use the BEGIN WORK, COMMIT WORK, or the ROLLBACK
WORK statements. You can use the START DATABASE statement to assign
a log file 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 file 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 data-
base.) 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 flag after a DATABASE statement in the SQLCA.SQLAWARN
structure. See the section “SQLCA Record” in Chapter 3 for more infor-
mation 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 trans-
action log file:
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

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 is a keyword to prevent duplicate entries in the column or
composite column to which the index applies.
CLUSTER is an optional keyword that causes the physical table to be
ordered according to the order of the index.
index-name is the SQL identifier you want to assign to the index. You
must assign a different identifier to each index in the
database.
ON is a required keyword.
table-name is the name of the table containing the column or columns
that you want to index.
column-name 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.
ASC is a keyword that specifies an index that INFORMIX-4GL
maintains in ascending order. ASC is the default.
DESC is a keyword that specifies an index that INFORMIX-4GL
maintains in descending order.

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 state-
ment cannot exceed 120 bytes.
4. See the section “Indexing Strategy” in Chapter 3 for a discussion of index-
ing 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 col-
umn 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 defined as UNIQUE in
a CREATE TABLE statement.
11. A column list defined as having a UNIQUE CONSTRAINT in a CREATE
TABLE statement receives a unique ascending composite index. You can-
not use the CREATE INDEX statement to create an identical unique
composite index.
12. In a composite index, you can include a column defined as UNIQUE. Sim-
ilarly, in a composite index you can include a composite column list
defined as UNIQUE. However, the column list in the CREATE INDEX state-
ment cannot be identical to the column list defined as UNIQUE in the
CREATE TABLE statement.
13. When more than one column is listed, the concatenation of the set of col-
umns 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

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 are required keywords.
synonym is an SQL identifier.
FOR is a required keyword.
table-name is the name of a table or view.

Notes
1. In a MODE ANSI database, the name of a synonym is qualified 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 prefix 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 state-
ment. 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 INFOR-
MIX-OnLine. Refer to the INFORMIX-OnLine Programmer’s Manual for more
information.

7-48 INFORMIX-4GL Statement Syntax

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 are required keywords.
TEMP is an optional keyword.
table-name is the SQL identifier that you assign to the table. The first
ten characters must be unique within a database.
column-name is the SQL identifier that you assign to each column.
datatype specifies the data type for each column. (See the following
list for valid SQL data types.)
NOT NULL are optional keywords to prevent entry of NULL values.
UNIQUE is an optional keyword specifying that the column or
composite unique-col-list cannot contain duplicate values.
(unique-col-list) is a list (in parentheses) of the names of columns to
include in a composite UNIQUE CONSTRAINT.
CONSTRAINT is a keyword to indicate that constr-name is assigned in the
statement.
constr-name is the name of the UNIQUE CONSTRAINT. A constr-name
must be a valid identifier that does not conflict with an
existing constraint name. It can be optionally prefixed
with the username of the owner of the table or, if you have
DBA privileges, the username of another user.

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.
IN is an optional keyword.
pathname specifies the full pathname in which to store the database
table, with no extension to the filename. A pathname can-
not be longer than 64 characters and must be enclosed
within quotes ( " ). A pathname is of the form:
[ /directory-name/ . . . ] filename
A list of valid SQL data types follows:
CHAR ( n ) is a character string of length n (where 1 ≤ n ≤ 32,511).
CHARACTER is a synonym for CHAR.
SMALLINT is a whole number from -32,767 to +32,767.
INTEGER is a whole number from -2,147,483,647 to +2,147,483,647.
INT is a synonym for INTEGER.
DECIMAL [(m[,n])] is a decimal floating-point number with a total of m (≤ 32)
significant 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.
DEC is a synonym for DECIMAL.
NUMERIC is a synonym for DECIMAL.
SMALLFLOAT is a binary floating-point number corresponding to the
‘‘float’’ data type in the C language.
REAL is a synonym for SMALLFLOAT.
FLOAT [(n)] is a binary floating-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.
DOUBLE is a synonym for FLOAT.
PRECISION
MONEY [(m[,n])] is a DECIMAL type number, displayed with leading $.
MONEY (m) = DECIMAL(m,2) and MONEY = DECI-
MAL(16,2). See the section “Database Data Types”’ in
Chapter 3 for more information.

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.
DATE is a date entered as a character string in one of the formats
described in the following notes.
DATETIME is a moment in time that can include the year, month, day,
hour, minute, second, and fraction of a second. See the fol-
lowing notes and the section “Database Data Types” in
Chapter 3 for more information.
INTERVAL 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.”

Notes
1. In a database created as MODE ANSI, the name of a table is qualified 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 prefix 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 dupli-
cate names in different tables in the same database. See “SQL Identifiers”
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 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 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. Repre-
sent 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 file space requirements (in bytes) for each
data type:
SERIAL 4
SMALLINT 2
INTEGER 4
SMALLFLOAT 4
FLOAT 8
CHAR(n) n
DECIMAL(m,n) 1 + m/2
MONEY(m,n) 1 + m/2
DATE 4
DATETIME Depends on precision (see below)
INTERVAL Depends on precision (see below)
Values in a DATETIME column are stored as decimal numbers, containing
a sequence of digits representing the following fields: year, month, day,
hour, minute, second, and fraction(n). All fields of a DATETIME column
occupy two digits, except for the year and fraction fields. The year field
requires four digits. The fraction field 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 fields, plus 1.
Values in an INTERVAL column are stored as decimal numbers, contain-
ing a sequence of digits representing the following fields: year and
month, or else year, month, day, hour, minute, second, and fraction(n). All

7-52 INFORMIX-4GL Statement Syntax

CREATE TABLE ( O )

fields of an INTERVAL column are represented by two digits, except for

the first field and the fraction field. The number of digits in the first field
is two, unless otherwise specified as part of the qualifier. The fraction field
requires n digits. The number of bytes required for an INTERVAL column
is equal to half the total number of digits for all fields, 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
specified 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 syscon-
straints 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 conflicts with an
existing identifier, 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 file 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 specifies a filename that is different from
the table-name, always use the table-name (rather than the filename) 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 fea-
ture 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 log-
ging. 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 SERIAL(1001),
order_date DATE,
customer_num INTEGER,
ship_instruct CHAR(40),
backlog CHAR(1),
po_num CHAR(10),
ship_date DATE,
ship_weight DECIMAL(8,2),
ship_charge MONEY(6),
paid_date DATE
)

CREATE TABLE items

(
item_num SMALLINT,
order_num INTEGER,

7-54 INFORMIX-4GL Statement Syntax

CREATE TABLE ( O )

stock_num SMALLINT,
manu_code CHAR(3),
quantity SMALLINT,
total_price MONEY(8)
)

CREATE TABLE stock

(
stock_num SMALLINT,
manu_code CHAR(3),
description CHAR(15),
unit_price MONEY(6),
unit CHAR(4),
unit_descr CHAR(15)
)

CREATE TABLE manufact

(
manu_code CHAR(3),
manu_name CHAR(15)
)

CREATE TABLE state

(
code CHAR(2),
sname 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 file /a/work/employ.dat. The index information is stored in the
file /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

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.
view-name is an SQL identifier.
column-list is a list of one or more identifiers that name the columns
of view-name.
AS is a required keyword.
SELECT-statement is a SELECT statement.
WITH CHECK are optional keywords.
OPTION

Notes
1. In a database created as MODE ANSI, the name of a view is qualified 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 prefix 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 specifications) where you can use a table.
ALTER TABLE DROP INDEX
ALTER INDEX LOCK TABLE
CREATE INDEX 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 reflects changes to the
underlying tables, but with one exception.
If the view is defined 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 col-
umn. 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 prefixes 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 non-
MODE ANSI database, view-name must be unique.
6. You can define 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 modifications to the underlying tables made through the view satisfy
the definition 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

Overview
Use the CURRENT WINDOW statement to make a window the current or top-
most window.

Syntax
CURRENT WINDOW IS { window-name | SCREEN }

Explanation
CURRENT are required keywords.
WINDOW IS
window-name is the name of the window that you want to be the current
window.
SCREEN is a keyword that refers to the entire screen.

Notes
1. A window becomes completely visible when it becomes the current win-
dow. 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 cur-
rent 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 specific 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

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.
database-name is the name of a database, or a program variable that evalu-
ates to the name of a database.
EXCLUSIVE is an optional keyword.

Notes
1. If you want to specify a database that does not reside in your current
directory or in a directory specified 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 data-
base (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 com-
piler where to find information about variables defined 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 defined LIKE database col-
umns, 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
define 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 flag after a DATABASE statement in the SQLCA.SQLAWARN
structure. See the section “SQLCA Record” in Chapter 3 for more infor-
mation 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

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.
cursor-name is an INFORMIX-4GL identifier.
SCROLL is an optional keyword that can be used only with a state-
ment or a statement_id of a SELECT statement that you
PREPAREd.
CURSOR FOR are required keywords.
WITH HOLD are optional keywords to prevent the cursor from being
closed when each transaction ends.
SELECT-statement is a SELECT statement.
FOR UPDATE are keywords that are required if the cursor will be used
to modify existing rows.
OF is an optional keyword.
column-list is a list of column names from tables listed in the FROM
clause of SELECT-statement.
INSERT-statement is an INSERT statement.
statement-id is the identifier of an INSERT or SELECT statement that
you previously PREPAREd.

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 flag, or if you have set the DBANSIWARN environment vari-
able 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 satisfied 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 state-
ment 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 state-
ment 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 con-
stant to indicate the array element.
Use FETCH INTO when the output variable is an array element sub-
scripted 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 state-
ment or when you CLOSE the cursor (whichever occurs first), 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 section“Locking” 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 cur-
sor 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
flushed 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 specifies the cursor. The cursor-name has meaning from the
point at which you DECLARE it, to the end of the same source file. It is not
a global identifier that can be referenced in a separate source file.
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

Overview
Use the DEFER statement to keep INFORMIX-4GL from terminating your pro-
gram whenever a user presses the Interrupt key (usually CTRL-C or DEL) or
the QUIT key (usually CTRL-\).

Syntax
DEFER { INTERRUPT | QUIT }

Explanation
DEFER is a required keyword.
INTERRUPT is an optional keyword.
QUIT is an optional keyword.

Notes
1. In the absence of the DEFER statement, your program will stop immedi-
ately whenever Interrupt or Quit is pressed.
2. The DEFER statement sets a global flag (int_flag for INTERRUPT and
quit_flag for QUIT) to non-zero whenever the user presses the Interrupt
or Quit key. The programmer must reset the flags to zero.
3. If the DEFER INTERRUPT statement has been executed and the user subse-
quently enters an Interrupt during an INPUT statement, program control
will leave the INPUT statement and int_flag 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

Overview
Use the DEFINE statement to define identifiers 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.
variable-list is one or more identifiers of program variable.
type is one of these data types (as defined in Chapter 2):
SMALLINT MONEY [ (m [ , n ] ) ]

INTEGER CHAR [ ( n ) ]
INT CHARACTER [ ( n ) ]

DECIMAL [ (m [ , n ] ) ] DATE
DEC [ ( m [ , n ] ) ]
NUMERIC [ (m [ , n ] ) ] DATETIME qualifier

SMALLFLOAT INTERVAL qualifier

REAL
RECORD [ LIKE table. * ]
FLOAT [ ( n ) ]
DOUBLE PRECISION [ ( n ) ] ARRAY [ i , j , k ] OF type
LIKE is a keyword to specify the data type indirectly.
table.column is the full identifier for a column in the current database. The
DATABASE statement must precede DEFINE statements that
use indirect typing.
RECORD is a data type that describes a set of variables of possibly
differing database data types.
table is the name of a database table.
END are keywords that follow the declaration of the last element of
RECORD a program record.

INFORMIX-4GL Statement Syntax 7-71

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 first 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 identifi-
ers 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 INFOR-

MIX -Online Programmer’s Manual for more information.

7-72 INFORMIX-4GL Statement Syntax

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 is the name of the table from which you want to delete rows.
WHERE is a keyword.
condition 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.
CURRENT OF are keywords.
cursor-name is the SQL identifier of a previously DECLAREd and posi-
tioned cursor.

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 opera-
tion 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 { field-list | screen-record [ [ n ] ].* } [ , . . . ]
| AT row, column ] }
[ ATTRIBUTE ( attribute-list ) ]

Explanation
DISPLAY is a required keyword.
BY NAME are keywords instructing INFORMIX-4GL to match the
names of variables with screen field names.
variable-list is a required list of one or more program variables and/or
constants, separated by commas.
TO is a keyword to specify that INFORMIX-4GL will display the
variable_list in screen fields or in a screen array.
field-list is a list of one or more screen field names in the current
screen form.
screen-record is the identifier of a collection of field names defined in a
form specification as a SCREEN RECORD.
[n] 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.
AT is a keyword to specify coordinates of a location on the
screen or in the current window.
row is an integer variable or constant, indicating a row of the
screen or current window.
column is an integer variable or constant, indicating a column of the
screen or current window.
ATTRIBUTE is a keyword to specify screen display attributes.
(attribute-list) is a list (in parentheses) of one or more screen display
attributes, separated by commas.

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 cur-
rent screen display until this statement is executed again.
3. INFORMIX-4GL displays number values right justified, and character
strings left justified in the screen field.
4. If a character value does not fit in the field, its display is truncated. If a
number value does not fit in the field, INFORMIX-4GL fills the field with
asterisks (*) to indicate an overflow.
5. The DISPLAY BY NAME option selects screen fields, based on the identity
of the program variable name and the field name. INFORMIX-4GL uses
only the suffix portion of these variable names and field names. This
option results in an error (setting status < 0) unless the suffixes are unique
and unambiguous.
6. The DISPLAY TO screen-record [n].* option lists constants or program vari-
ables 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 specified
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 specifies a location, a compile-time error

occurs if you use the ATTRIBUTE clause.
13. In a DISPLAY TO statement, any screen attributes specified in attribute-list
apply to all the fields in field-list or screen-record.
14. If you use the ATTRIBUTE clause, none of the default attributes listed
in syscolatt or in the form specification file for fields in field-list or
screen-record apply. The attribute-list temporarily overrides any attributes
specified in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement
for these fields.
15. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
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 inter-
preted 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 files 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 first 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 first character of the variable-list is a
blank if you specify any display attributes.
16. On UNIX systems that use terminfo files rather than termcap, INFOR-
MIX-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

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.
record-array is a program array name. Usually, record-array is an array
of records.
TO is a required keyword.
screen-array is the name of a screen record, defined in a form specifica-
tion file, that corresponds to the fields in a row of a screen
array.
ATTRIBUTE is an optional keyword.
attribute-list is a list of one or more screen-display attributes.
ON KEY are optional keywords.
key-list is usually a list of one or more function or CTRL key des-
ignations. It can also include ESC (if you have specified
another key as the Accept key in the OPTIONS statement)
or INTERRUPT (if you have executed a DEFER INTERRUPT
statement).
statement is an INFORMIX-4GL statement.
EXIT DISPLAY is a statement that causes INFORMIX-4GL to exit from the
DISPLAY ARRAY statement.
END DISPLAY is a statement that terminates a DISPLAY ARRAY state-
ment. It is required only when an ON KEY clause is used,

INFORMIX-4GL Statement Syntax 7-79

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 filled 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 define the key assignments properly in the termcap or
terminfo files.
3. The user can exit from the DISPLAY ARRAY statement by pressing ESC, or
by pressing the key specified as the ACCEPT KEY in the OPTIONS state-
ment. 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-justified and
character variables left-justified in the screen field.
6. If a displayed character value is larger than the field, INFORMIX-4GL
truncates the value. If a displayed number value is larger than the field,
INFORMIX-4GL fills the field with asterisks (*).
7. The attributes listed in attribute-list apply to all the fields in screen-array.
8. If you use the ATTRIBUTE clause, none of the default attributes listed in
syscolatt or in the form specification file for the fields 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 REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
On color terminals, NORMAL is interpreted as WHITE; BOLD as RED; DIM
as BLUE; and INVISIBLE as BLACK. If you have a colornames file, 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 state-
ments 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 nota-
tion 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 Inter-
rupt 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_flag to non-zero, and ter-
minates the DISPLAY ARRAY statement (unless the Interrupt key has been
redefined in an ON KEY clause). Otherwise, an Interrupt causes an imme-
diate program stop.
13. You can include the following keys in a key-list under the stated
conditions:
• ESCAPE, if you have specified another key as the Accept key in the
OPTIONS statement.
• [ F3 ], if you have specified another key as the Next key in the OPTIONS
statement.
• [ F4 ], if you have specified another key as the Previous key in the
OPTIONS statement.
• The Interrupt key, if you have executed a DEFER INTERRUPT state-
ment. (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_flag 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

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 is an INFORMIX-4GL identifier that has been associated with
a screen form in an OPEN FORM statement.
ATTRIBUTE is an optional keyword.
attribute-list 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
fields.

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 win-
dows (including the screen) by using the OPTIONS statement or for a
specific 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 REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM
as BLUE, and INVISIBLE as BLACK. If you have a colornames file, 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 display-
ing a form in a window.
4. The DISPLAY FORM statement is not required if you opened and dis-
played 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

Overview
Use the DROP AUDIT statement to delete an audit trail file.

Syntax
DROP AUDIT FOR table-name

Explanation
DROP AUDIT FOR are required keywords.
table-name is the name of the table whose audit trail file you want
to delete.

Notes
1. Us e the DROP AUDIT statement to remove the old audit trail file when
you have made a backup of your database files. Use the CREATE AUDIT
statement to start a new audit trail and then back up the table. See the sec-
tion “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

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.
database-name is the name of the database you want to delete.
char-variable is a program variable of type CHAR containing the
name of the database you want to delete.

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 files 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 first.
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

Overview
Use the DROP INDEX statement to delete an index.

Syntax
DROP INDEX index-name

Explanation
DROP INDEX are required keywords.
index-name is the name of the index you want to delete.

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 identified 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

Overview
Use the DROP SYNONYM statement to delete a previously defined synonym
for a table or view.

Syntax
DROP SYNONYM synonym

Explanation
DROP SYNONYM are required keywords.
synonym is a 4GL identifier.

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 identifier 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

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.
table-name is the name of the table you want to delete.

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

Overview
Use the DROP VIEW statement to delete a view from the database.

Syntax
DROP VIEW view-name

Explanation
DROP VIEW are required keywords.
view-name is the identifier of a view.

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 defined
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

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.
display-list is a list of one or more program variables and/or string con-
stants (enclosed in quotation marks), separated by commas.
ATTRIBUTE is an optional keyword.
attribute-list is a list of one or more screen attributes, separated by
commas.

Notes
1. The string generated by substituting values for the variables in display-list
must fit 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 REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM
as BLUE, and INVISIBLE as BLACK. If you have a colornames file, 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

Overview
Use the EXECUTE statement to run a statement specified by a previous
PREPARE statement.

Syntax
EXECUTE statement-id [ USING input-list ]

Explanation
EXECUTE is a required keyword.
statement-id is an SQL statement identifier that you named in a previous
PREPARE statement.
USING is an optional keyword.
input-list 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.

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 pro-
cess 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 state-
ment 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

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 is a required keyword.
CASE is an optional keyword.
DISPLAY is an optional keyword.
FOR is an optional keyword.
FOREACH is an optional keyword.
INPUT is an optional keyword.
MENU is an optional keyword.
PROGRAM is an optional keyword.
integer-expr is an expression that evaluates as an integer.
WHILE is an optional keyword.

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 first 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

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 is a required keyword.
NEXT is a keyword indicating the next row in the active list. NEXT
is the default.
PREVIOUS is a keyword indicating the prior row in the active list.
PRIOR is a keyword that is synonymous with PREVIOUS.
FIRST is a keyword indicating the first row of the active list.
LAST is a keyword indicating the last row of the active list.
CURRENT is a keyword indicating the current row of the active list.
RELATIVE m is a keyword indicating the mth row relative to the current
cursor position in the active list. Here m can be either an inte-
ger or a program variable and can be either positive or
negative.
ABSOLUTE n is a keyword indicating the nth row in the active list. Here n
can be either an integer or a program variable.
cursor-name is a 4GL identifier that you specified in a previous DECLARE
statement. You must also OPEN cursor-name.
INTO is an optional keyword.
variable-list is a list of 4GL program variables that contains the column
values of the row pointed to by cursor-name.

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 first 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

Overview
Use the FINISH REPORT statement to cause INFORMIX-4GL to finish
processing a report.

Syntax
FINISH REPORT report-name

Explanation
FINISH REPORT are required keywords.
report-name is the identifier of a report.

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

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.
cursor-name is the name of a cursor that has been DECLAREd for an
INSERT statement.

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 data-
base, 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 (specifi-
cally, 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 automati-
cally flushes the buffer when it is full.
3. Insert cursors that contain only constants in the values clause are not buff-
ered. 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
unflushed. Rows inserted into the buffer and remaining since the last
flush are lost. Do not expect the end of program to close the cursor and
flush 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

Overview
Use the FOR statement to cause a sequence of statements to be executed a
specified 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.
integer-var is a program variable of type INTEGER or SMALLINT that
serves as a counter.
integer-expr is an expression that evaluates to an INTEGER or a SMALL-
INT.
TO is a required keyword.
STEP is an optional keyword.
statement is an INFORMIX-4GL statement.
CONTINUE FOR is an optional statement.
EXIT FOR is an optional statement.
END FOR are required keywords.

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 first 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 first 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

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.
cursor-name is the name of a cursor that previously was
DECLAREd.
INTO is an optional keyword.
variable-list is a list of one or more program variables, separated
by commas.
CONTINUE FOREACH is an optional statement.
EXIT FOREACH is an optional statement.
END FOREACH are required keywords.

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 cursor-
name. The FOREACH statement OPENs the cursor and performs succes-
sive 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 pro-
gram control to jump to the first 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
first statement following END FOREACH. If you need to know whether
any rows were returned, you can set up a flag or a counter as in the exam-
ple that follows these notes.
7. The FOREACH statement performs an implied OPEN statement. You can-
not use the FOREACH statement if the OPEN statement must have a USING
clause to define 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 state-
ment 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 )

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.
statement-id is the name of a statement that has been PREPAREd.
cursor-name is the name of a cursor whose DECLARE statement includes
the keywords SELECT or INSERT.

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 cur-
sor 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

Overview
Use the FUNCTION statement to define a function.

Syntax
FUNCTION function-name ( [ argument-list ] )
statement
...
[ RETURN expr-list ]
...
END FUNCTION

Explanation
FUNCTION is a required keyword.
function-name is a program identifier for the name of the function.
(argument-list) is a list (enclosed in parentheses) of one or more variables,
separated by commas.
statement is an INFORMIX-4GL statement.
RETURN is an optional keyword that causes program control to
return to the calling program.
expr-list is a list of zero or more expressions that yield the values
returned by function-name.
END FUNCTION are required keywords that terminate the FUNCTION
statement.

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 define 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 identifiers, as
described in Chapter 2. An error results if function-name is the same as the
identifier of a global variable or of another function in the same program.

Related Statement
CALL

INFORMIX-4GL Statement Syntax 7-111

GLOBALS

Overview
Use the GLOBALS statement to DEFINE one or more variables to be global
variables or to refer to the file where global variables are DEFINEd.

Syntax
GLOBALS {‘‘filename’’ |
DEFINE-statement
...
END GLOBALS}

Explanation
GLOBALS is a required keyword.
filename is the pathname of the file where the global variables
are defined.
DEFINE-statement is a DEFINE statement for the global variable.
END GLOBALS are required keywords that terminate the GLOBALS
statement when variables are DEFINEd.

Notes
1. You may have at most one GLOBALS statement where global variables are
defined. This statement may be in a separate file or in the file containing
the MAIN program block.
2. The GLOBALS filename statement must occur earlier in every file 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

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 prefix to label-id and conforms to the ANSI standard
for SQL syntax.
label-id is a 4GL identifier.

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

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.
tab-privilege is one or more of the following table-level access types (mul-
tiple privileges must be separated by commas):
ALTER Add or delete columns or modify data types
of columns.
DELETE Delete rows.
INDEX Create indexes.
INSERT Insert rows.
SELECT [(cols)] Retrieve data from specified columns.
UPDATE [(cols)] Change values in specified columns.
ALL of the above access types.
[ PRIVILEGES ]
SELECT and UPDATE take column names as
arguments, allowing you to specify col-
umns that the user may select or update.
Separate column names with commas.

The keyword PRIVILEGES following ALL is

optional.
ON is a required keyword.
table-name is the name of the table or view for which you are granting
access privileges.
TO is a required keyword.
INFORMIX-4GL Statement Syntax 7-115
GRANT

PUBLIC is the keyword that you use to specify access privileges for
all users.
user-list is a list of login names for the users to whom you are grant-
ing access privileges. You can enter one login name or a
series of login names, separated by commas.
WITH GRANT are optional keywords.
OPTION
AS is an optional keyword.
grantor is the username of the user issuing the GRANT statement.
db-privilege is one of the following database-level access types:
CONNECT Allows access to database tables without per-
mission to create permanent tables and
indexes.
RESOURCE Allows access to database tables with permis-
sion to create permanent tables and indexes.
DBA Allows full database administrator privileges.

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 INFOR-
MIX also has permission to alter the system catalogs.
• Permission to grant and revoke CONNECT, RESOURCE, and DBA priv-
ileges 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 privi-
leges 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

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.
Boolean-expr is an expression that can be TRUE or FALSE.
THEN is a required keyword.
statement is any INFORMIX-4GL statement, including another IF
statement.
ELSE is an optional keyword.
END IF are required keywords.

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

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

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.
variable-list is a list of one or more variables, separated by commas.
LIKE is an optional keyword.
column-list is a list of column names, preceded by table names and sep-
arated by commas.
TO NULL are optional keywords to assign NULL values.

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 prefix in the designation of the column names.
3. In a MODE ANSI database, the name of a table is qualified 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 prefix 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 specified 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 vari-
ables that correspond to columns in tables owned by the specified user. If

7-120 INFORMIX-4GL Statement Syntax

INITIALIZE

no owner name is specified, 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

Overview
Use the INPUT statement to assign values to program variables from data that
the user enters into fields of a screen form.

Syntax
INPUT { BY NAME variable-list [ WITHOUT DEFAULTS ] |
variable-list [ WITHOUT DEFAULTS ]
FROM { field-list | screen-record [ [ n ] ] .* } [ , . . . ] }
[ ATTRIBUTE ( attribute-list ) ]
[ HELP help-number ]
[ { BEFORE FIELD field-sublist
| AFTER { FIELD field-sublist | INPUT }
| ON KEY ( key-list ) }
statement
...
[ NEXT FIELD field-name ]
...
[ EXIT INPUT ]
...
...
END INPUT ]

Explanation
INPUT is a required keyword. The INPUT statement allows the user
to change the data displayed on the screen.
BY NAME are keywords instructing INFORMIX-4GL to match names of
variables to screen field names.
variable-list is a list of program variables to display.
WITHOUT are keywords to display on the screen the current values in
DEFAULTS variable-list.
FROM is a keyword to specify the screen fields whose values will be
assigned to variable-list.
field-list is a list of one or more names of screen fields.
screen-record is the identifier of a collection of field names defined in a
form specification as a SCREEN RECORD.
[n] is an integer, enclosed in brackets, to specify the row of a
screen array (beginning with line 1).

7-122 INFORMIX-4GL Statement Syntax

INPUT

ATTRIBUTE is a keyword to specify screen input attributes.

(attribute-list) is a list (in parentheses) of screen attributes.
HELP is a keyword to specify a help message.
help-number is an integer to identify a help message for this INPUT state-
ment in the help file that was specified in the OPTIONS
statement.
BEFORE FIELD are keywords to transfer control to a 4GL statement when the
cursor enters a field in the field-sublist.
field-sublist is a list of one or more of the fields either explicitly or implic-
itly referenced in the INPUT statement.
AFTER FIELD are keywords to transfer control to a 4GL statement when the
cursor leaves a field in the field-sublist.
AFTER INPUT are keywords to transfer control to a 4GL statement when the
user has finished entering input.
ON KEY are keywords to specify keys of the keyboard.
(key-list) 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.
statement is a 4GL statement. It is executed during input, if BEFORE
FIELD, AFTER FIELD, or ON KEY clause conditions are satis-
fied. It is executed after input, if an AFTER INPUT clause is
used.
NEXT FIELD are keywords that cause INFORMIX-4GL to move the cursor
immediately to a specified field.
field-name identifies a field from field-list or screen-record (or implied by
the BY NAME clause).
EXIT INPUT are keywords that direct INFORMIX-4GL to leave the INPUT
statement immediately.
END INPUT are keywords that terminate the INPUT statement. These
keywords are required if you include a BEFORE clause,
AFTER clause, or ON KEY clause.

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 fields. 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, INFOR-
MIX-4GL displays on the form the default values from the form
specification (or from syscolval, if no default valuess were specified by
the DEFAULT attribute in the form specification) and initializes the vari-
ables 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 fields based on the identity
of the program variable name and the screen field name. INFORMIX-4GL
uses only the suffix portion of the name of the program variable and the
screen field. You must use the FROM option if the suffixes 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 field names in field-list or screen-record, and
of the corresponding data type.
5. INPUT is terminated when the user presses ESCAPE (or the key specified
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 field to override the ter-
minating power of the RETURN by setting NEXT FIELD to the first field.
This option wraps the field-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 state-
ments 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 field in field-list. It passes control to the
statements following an AFTER clause when the cursor leaves a field in
field-list (after the user has pressed RETURN, indicating that data has been

7-124 INFORMIX-4GL Statement Syntax

INPUT

entered into the field). 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 follow-
ing a BEFORE or AFTER clause, the cursor moves to the next field 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 field,
INFORMIX-4GL suspends the input of the current field while it executes
the statements in the ON KEY clause. It preserves the input buffer contain-
ing 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 field with the cursor at the end of the buffered list of charac-
ters. If you want to use the ON KEY clause to fill the field with another
value, be sure to move to a new field 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 CON-
TROL 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 state-
ment. If the DEFER INTERRUPT statement has been executed, an Interrupt
causes INFORMIX-4GL to set the global variable int_flag to nonzero and
terminate the INPUT statement (unless the function of Interrupt is rede-
fined 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 specified 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, INFOR-
MIX-4GL executes the statements in the ON KEY clause and sets
int_flag 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.
• Other keys that may have special meaning on your system, such as
CTRL-S for XOFF.
13. Use of CTRL-I and CTRL-J in a key-list can conflict 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 toggles between insert and typeover mode.
CTRL-D deletes characters from the current cursor position to the end
of the field.
CTRL-H moves the cursor nondestructively one space to the left
inside a field. It is equivalent to pressing the [ ←] key.
CTRL-L moves the cursor nondestructively one space to the right
inside a field. It is equivalent to pressing the [→] key.
CTRL-R redisplays the screen.
CTRL-X deletes the character beneath the cursor.
15. Function infield(field) from the function library returns TRUE if the cur-
rent field is field, and FALSE otherwise. Use it to make field-dependent
responses when the user presses a key specified in the key-list of an ON
KEY clause. If you call infield(field) outside the INPUT statement, it returns
a value corresponding to the field 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, how-
ever, call a function that executes one of these statements.
17. If you do not use the ATTRIBUTE clause, the display attributes of the input
fields 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
specifications.)
18. In an INPUT statement, any screen attributes specified in attribute-list
apply to all the fields in field-list or screen-record.
19. If you use the ATTRIBUTE clause, no default attributes in syscolatt or
in the form specification file for fields in field-list or screen-record apply
(including any default values from the DEFAULT attribute). The
attribute-list temporarily overrides any attributes specified in an
OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these fields.

7-126 INFORMIX-4GL Statement Syntax

INPUT

20. These keywords can appear in the ATTRIBUTE clause:

WHITE = NORMAL REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
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 inter-
preted 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 files 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 first 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 fields in any line of a screen form begin after column 1,
if you specify display attributes.
21. On UNIX systems that use terminfo files rather than termcap, INFOR-
MIX-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

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 field-sublist } [ , . . . ]
| AFTER { ROW | INSERT | DELETE |
FIELD field-sublist | INPUT } [ , . . . ]
| ON KEY ( key-list ) }
statement
...
[ NEXT FIELD field-name ]
...
[ EXIT INPUT ]
...
...
END INPUT ]

Explanation
INPUT ARRAY are required keywords.
record-array is a program array name. Usually, record-array is an array of
records.
WITHOUT are optional keywords to display the current values of
DEFAULTS record-array.
FROM is a required keyword.
screen-array is the name of a screen record that corresponds to the fields
in a row of a screen array.
HELP is an optional keyword.
help-number is an integer that identifies the help message for this INPUT
ARRAY statement in the help file set in the OPTIONS
statement.
ATTRIBUTE is a keyword to specify screen input attributes.
(attribute-list) is a list (in parentheses) of screen attributes.
INFORMIX-4GL Statement Syntax 7-129
INPUT ARRAY

BEFORE is an optional keyword.

ROW is an optional keyword.
INSERT is an optional keyword.
DELETE is an optional keyword.
FIELD is an optional keyword.
field-sublist is a list of one or more fields taken from screen-array.*.
AFTER is an optional keyword.
INPUT is an optional keyword.
ON KEY are optional keywords.
key-list is usually a list of one or more function or CTRL key designa-
tions. The list can also include ESCAPE (if you have specified
another key as the Accept key in the OPTIONS statement) or
Interrupt (if you have executed a DEFER INTERRUPT state-
ment).
statement is any INFORMIX-4GL statement.
NEXT FIELD is an optional statement that causes the cursor to move
immediately to the next field.
field-name is a field name to which the cursor should move.
EXIT INPUT is an optional statement directing INFORMIX-4GL to leave
the INPUT ARRAY statement immediately.
END INPUT 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.

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
definition 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 first row of screen-array
and record-array with the default values from the form specification (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 ini-

7-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 defined size of the record-
array, 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
fill 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 field. At the end of the screen field, it causes
a jump to the first character position of the next screen
field.
LEFT ARROW moves the cursor non-destructively one space to the
left inside a screen field. At the end of the screen field,
it causes a jump to the first character position of the
previous screen field.
DOWN ARROW 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.
UP ARROW moves the cursor up one row on the screen. If the cur-
sor was on the first row before the user pressed [ ↑ ],
the displayed data moves down one row. If the first
program array row is already on the first screen array
row, [ ↑ ] does nothing.
F3 scrolls the display to the next full page of program
array rows. You can reset this key using the OPTIONS
statement.
F4 scrolls the display to the previous full page of pro-
gram array rows. You can reset this key using the
OPTIONS statement.

INFORMIX-4GL Statement Syntax 7-131

INPUT ARRAY

7. The INPUT ARRAY statement is terminated when the user enters ESC or
the key you specified 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 valid-
ity 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 fields in a row of screen-array and of the corresponding data
type.
9. INFORMIX-4GL executes BEFORE, AFTER, and ON KEY clauses in the fol-
lowing 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 field.
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 field.

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 neces-
sarily 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 specified as the Accept
key in the OPTIONS statement.
20. If there is no NEXT FIELD statement in the sequence of statements follow-
ing a BEFORE or AFTER clause, the cursor moves to the next field in the
direction that the user indicated (forward for [ → ] or RETURN and back-
ward for [ ← ]).
21. If the user triggers an ON KEY clause while entering data into a field,
INFORMIX-4GL suspends the input of the current field 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 field with the cursor at the end of the buffered list of
characters. If you want to use the ON KEY clause to fill the field with
another value, be sure to move to a new field with the NEXT FIELD state-
ment 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 INFOR-
MIX-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_flag to nonzero and terminate
the INPUT ARRAY statement (unless the function of Interrupt has been
redefined in an ON KEY clause). Otherwise, an Interrupt causes an imme-
diate 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 specified another key as the Accept key in the
OPTIONS statement.
• [ F1 ] if you have specified another key as the Insert key in the
OPTIONS statement.
• [ F2 ] if you have specified another key as the Delete key in the
OPTIONS statement.
• [ F3 ] if you have specified another key as the Next key in the OPTIONS
statement.
• [ F4 ] if you have specified 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_flag 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 conflict 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 toggles between insert and typeover mode.

CTRL-D deletes characters from the current cursor position to the end of
the field.
CTRL-H moves the cursor non-destructively one space to the left inside
a field.
CTRL-L moves the cursor non-destructively one space to the right
inside a field.
CTRL-R redisplays the screen.
CTRL-X deletes the character beneath the cursor.
27. The function infield(field) from the function library returns TRUE if the
current field is field and FALSE otherwise. It can be used to make field-
dependent 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 infield(field) outside the INPUT ARRAY state-
ment, it returns a value corresponding to the field 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. How-
ever, 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 defined 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 execu-
tion of the block.
arr_count( ) returns the total number of filled rows in record-array.
scr_line( ) returns the current row of screen-array. The current row is
defined in the same way that the current row for
arr_curr( ) is defined.
set_count( ) takes an argument that is the total number of filled rows
in record-array. You must call this function before execut-
ing the INPUT ARRAY WITHOUT DEFAULTS, so that the
program knows the initial value of arr_count( ).
30. If you do not use the ATTRIBUTE clause, the display attributes of the input
fields 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
specifications.)
31. In an INPUT ARRAY statement, any screen attributes specified in
attribute-list apply to all the fields in field-list or screen-record.
32. If you use the ATTRIBUTE clause, none of the default attributes listed in
syscolatt or in the form specification file for fields in field-list or
screen-record apply (including any default values from the DEFAULT
attribute). The attribute-list temporarily overrides any attributes specified
in an OPTIONS, DISPLAY FORM, or OPEN WINDOW statement for these
fields.

INFORMIX-4GL Statement Syntax 7-135

INPUT ARRAY

33. These keywords can appear in the ATTRIBUTE clause:

WHITE = NORMAL REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
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 inter-
preted 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 files 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 first 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 fields in any line of the screen form begin after
column 1, if you specify display attributes.
34. On UNIX systems that use terminfo files rather than termcap, INFOR-
MIX-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
first_data. The program recalculates and displays the row number after the
user inserts new rows or deletes old ones.
DEFINE pa_total INTEGER # total number of rows
# in program array
DEFINE pa_curr INTEGER # current program array
# row number
DEFINE sc_curr INTEGER # current screen array
# row number
DEFINE sc_total INTEGER # total number of rows
# in screen array
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

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.
table-name is the name of the table to which to add rows.
column-list is a list of the names of the columns into which to insert
data. You can enter one column name or a series of col-
umn names, separated by commas.
VALUES is a keyword.
value-list are the values to insert into the columns that you speci-
fied. You can enter one or more program variables or con-
stants, separated by commas.
SELECT-statement is a valid SELECT statement.

Notes
1. INFORMIX-4GL inserts data into the columns in the specified table in the
order in which you enter column names. It inserts the first value that you
enter into the first 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 defined 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 buff-
ers 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 rep-
resentation 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 defined 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 ROLL-
BACK 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 oper-
ation 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 con-
verted, 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

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.
label-id: is an INFORMIX-4GL identifier, followed by a colon ( : ).

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 is a required keyword.
variable is the identifier of a simple program variable.
expr 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 val-
ues 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

Overview
Use the LOAD statement to fill an existing table with data taken from an ASCII
file.

Syntax
LOAD FROM "pathname" [ DELIMITER "char" ]
{ INSERT INTO table-name [ ( column-name [ , . . . ] ) ]
| INSERT-stmt }

Explanation
LOAD FROM are required keywords.
pathname is a character variable or constant that evaluates to the path-
name of a file that contains rows of data.
DELIMITER is an optional keyword to indicate that the following char
appears at the end of each data field in the file.
char is a CHAR variable or a quoted string containing exactly one
character.
INSERT INTO are keywords to specify where to store the data.
table-name is the identifier of an existing table.
column-name is a column name (in parentheses) in table-name.
INSERT-stmt 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.

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 file 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 file can contain the delimiter character.
Use a backslash to escape the delimiter character and prevent its interpre-
tation as a field delimiter.
4. The LOAD statement can accept the format of data from a file written by
the UNLOAD statement (described later in this chapter).
5. The number of data fields in the load file must equal the number of col-
umns in the table (or in the optional list of column names).
6. The order and data type of the data fields in the file must match the order
and data type of the columns specified in the database table. There must
be exactly as many delimited fields in each line of the file as the number
of columns that you imply or specify in the INTO clause. The length of
each data field must be less than or equal to the length specified for each
column of the database table. The value in each field 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 file.
8. A NULL column should be represented in the input file by no characters
between delimiters.
9. A blank CHAR column should be represented in the input file by one or
more blank characters between delimiters.
10. It is permissible to have leading blanks in number, DATE, and MONEY
fields.
11. DATE fields 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 field is mm/dd/yy, the yy is interpreted as 19yy. Any
value in a DATE field must be a legal date (for example, February 30 is
illegal).
12. MONEY fields can have leading currency symbols.
13. DATETIME and INTERVAL values must be in character form, showing
only field digits and delimiters (with no type specification or qualifiers).
The required pattern is the substring of yyyy-mm-dd hh:mi:ss.fff, which cor-
responds to the qualifier 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 INFOR-

MIX-OnLine Programmer’s Manual for more information.

INFORMIX-4GL Statement Syntax 7-145

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.
table-name is the name of the table you want to lock.
IN is a required keyword.
SHARE 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.
EXCLUSIVE is a keyword to prevent other users from having any access
to the table.
MODE is a required keyword.

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 first 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. Nor-
mally, 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 sys-
tem 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 table-
level 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

Overview
Use the MAIN keyword to introduce the MAIN program block.

Syntax
MAIN
statement
...
END MAIN

Explanation
MAIN is a required keyword.
statement is any INFORMIX-4GL statement except MAIN.
END MAIN are required keywords that terminate the MAIN program
block.

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

Overview
Use the MENU statement to create a menu screen, to define user menu
options, to designate help numbers, and to define 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.
menu-name is a character string giving the title of the menu.
COMMAND is a required keyword.
KEY is an optional keyword.
key-list is a list of one or more letters, function key identifiers,
or CTRL key identifiers, separated by commas. You do
not need to put quotation marks around single, print-
able characters.
menu-option is a single-word label for a menu option. The
menu-option must be enclosed in quotation marks ( " ).
helpline is a one-line character string describing the
menu-option. The helpline must be enclosed in
quotation marks ( " ).
HELP is an optional keyword.

INFORMIX-4GL Statement Syntax 7-149

help-number is the number of the help message in the help file des-
ignated in the OPTIONS statement that corresponds to
menu-option.
statement is an INFORMIX-4GL statement that you want executed
when the user selects the preceding option. Several
statements can exist for each option.
CONTINUE MENU is an optional statement that returns program control
to the current MENU statement.
EXIT MENU is an optional statement that causes program control to
move to the first statement following the END MENU
keywords.
NEXT OPTION are optional keywords that precede the menu option
that you want highlighted when you return to the
menu.
END MENU are required keywords that terminate the MENU
statement.

Notes
1. You must define at least two options (COMMAND clauses) for each menu.
2. The menu screen displays in a ring menu each of the single-word menu-
options 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 first ‘‘page’’ of options followed by an ellipsis ( . . . ) indicating that
additional options exist. For example,

menu-name: menu-option1 menu-option2 menu-option3 menu-option4 ...

optional Help line

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

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 menu-option6 menu-option7 menu-option8 ...

optional Help line

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 menu-option10 menu-option11

optional Help line

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 first page of
menu options by using the [ → ] key to move the highlight past the right-
most option in the example.
The [ ↑ ] key moves the highlight to the first item on the previous page;
the [ ↓ ] key moves the highlight to the first item on the subsequent page.
4. The help-number refers to the number of the help message in the help file
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 file, or if the help file does not
exist.
6. You will incur a run-time error if the menu cannot fit on the screen or in
the current window.

INFORMIX-4GL Statement Syntax 7-151

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 first
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 redis-
plays 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 nota-
tion 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 defined.
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 fol-
lowing example.

7-152 INFORMIX-4GL Statement Syntax

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 Delete Exit

Add a row to the database

Related Command
OPTIONS

INFORMIX-4GL Statement Syntax 7-153

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.
display-list is a list of one or more program variables and/or string con-
stants (enclosed in quotation marks), separated by commas.
ATTRIBUTE is an optional keyword.
attribute-list is a list of one or more screen attributes, separated by
commas.

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 REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
On color terminals, NORMAL is interpreted as WHITE, BOLD as RED, DIM
as BLUE, and INVISIBLE as BLACK. If you have a colornames file, 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

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.
cursor-name is the identifier of a previously declared cursor.
USING is a keyword, needed only if the cursor expects user-sup-
plied search values.
variable-list is a list of program variables, separated by commas, corre-
sponding to the ‘‘?’’ parameters in a query associated with a
SELECT cursor.

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 satisfies the WHERE clause. This
set of rows is called the active set. It leaves the cursor in an open state and
pointing before the first row of the active set.
2. The active set is a dynamic collection of rows; it is not fixed at the time
when the OPEN statement is executed. Rows meeting the WHERE criteria
and qualified for FETCHing depend on the activity in the table.
3. Once the active set for a SELECT cursor is determined, the program vari-
ables 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 can-

not 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
flushes the INSERT buffer (that is, INFORMIX-4GL inserts any rows cur-
rently 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 non-
UPDATE 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 ROLL-
BACK 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 PRE-
PAREd 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

Overview
Use the OPEN FORM statement to associate an INFORMIX-4GL identifier with
a pre-compiled screen form.

Syntax
OPEN FORM form-name FROM "form-file"

Explanation
OPEN FORM are required keywords.
form-name is an INFORMIX-4GL identifier.
FROM is a required keyword.
form-file is the pathname of a compiled screen form (omitting the
extension .frm). form-file must be enclosed in quotation
marks.

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 state-
ment for that form. If you have displayed another form and wish to regain
the space used by the first 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

Overview
Use the OPEN WINDOW statement to create and open a window at a specified
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-file" }
[ ATTRIBUTE ( attribute-list ) ]

Explanation
OPEN WINDOW are required keywords.
window-name is the name of the window that you want to create.
AT is a required keyword.
row is an integer or integer variable between one and the max-
imum number of lines allowed by your terminal (usually
24), indicating the line on the screen where the top of the
window will appear.
column is an integer or integer variable between one and the max-
imum number of columns allowed by your terminal
(usually 80), indicating the column of the screen where
the left margin of the window will appear.
WITH is a required keyword to specify the vertical and horizon-
tal dimensions of the window, in characters.
integer is an integer or integer variable.
ROWS is a keyword to specify the height of the window.
COLUMNS is a keyword to specify the width of the window.
FORM is an optional keyword.
form-file is the pathname of a compiled form specification file
(excluding the .frm extension).
ATTRIBUTE is an optional keyword.
(attribute-list) is a list of one or more window display attributes.

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 identifier 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 INFOR-
MIX-4GL automatically opens a window sized to the screen layout of
form-file and displays the form. INFORMIX-4GL determines the width of
the window from the rightmost character of the screen form and calcu-
lates 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-file.
(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 win-
dow 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 specified in
the most recently executed OPTIONS statement for the Prompt, Message,
Form, and Comment lines. Values are relative to the first or last line of the
newly opened window. To change the values for these reserved lines
(without disabling the OPTIONS statement specifications for other win-
dows), 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 Default Setting

BORDER No border
color (see note 13) The default foreground color on your terminal
REVERSE No reverse video
PROMPT LINE line-value FIRST ( = 1 )
MESSAGE LINE line-value FIRST + 1 ( = 2 )
FORM LINE line-value FIRST + 2 ( = 3 )
COMMENT LINE line-value 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 specified 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 spec-
ify with the PROMPT, MESSAGE, or DISPLAY statement (or with the
COMMENTS attribute of a screen form), INFORMIX-4GL generates a run-
time error.
9. INFORMIX-4GL displays system error messages and text associated with
the ERROR statement in a borderless window on the Error line. INFOR-
MIX-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 state-
ment 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 out-
side 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 defined in the termcap
or terminfo files. You can specify alternative border characters in these
files. 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 files.
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 col-
umns to the right.
13. Use any of the following keywords for color in an ATTRIBUTE clause to
specify the foreground of a window:
WHITE RED BLUE INVISIBLE
YELLOW CYAN BLACK BOLD
MAGENTA GREEN DIM NORMAL
14. If you specify a color in the ATTRIBUTE clause of an OPEN WINDOW state-
ment, 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 CUR-
RENT 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

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 oper-
ations 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-file" |
HELP KEY key-name |
INPUT ATTRIBUTE ( attribute-list ) |
DISPLAY ATTRIBUTE ( attribute-list ) } [ , . . . ]

Explanation
OPTIONS is a required keyword.
line-value is an integer expression, indicating the line of the current
window or screen to display the reserved line specified by
the preceding keywords. The line-value can include the key-
words FIRST or LAST.
MESSAGE are optional keywords to position the Message line. The
LINE default line-value is FIRST + 1 (that is, line 2 of the current
window).
PROMPT are optional keywords to position the Prompt line. The
LINE default line-value is the FIRST window line.
COMMENT are optional keywords to position the Comment line. The
LINE default line-value is LAST - 1 for the screen, and LAST for all
other windows.
ERROR LINE 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

OPTIONS

FORM LINE are optional keywords to position the first line of a form. The
default line-value is FIRST + 2 (that is, the form will begin on
line 3 of the current window).
INPUT WRAP are optional keywords indicating that the cursor wraps
around the list of input fields during the execution of an
INPUT or CONSTRUCT statement until the Accept key is
pressed. The default is INPUT NO WRAP.
INPUT are optional keywords indicating that the INPUT or
NO WRAP CONSTRUCT statement terminates upon a RETURN after the
last field. This option is the default.
key-name designates or a function or CTRL key whose action is speci-
fied by preceding keywords.
INSERT KEY 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 ].
DELETE KEY are optional keywords to specify the key that deletes a line
in INPUT ARRAY statements. The default is [ F2 ].
NEXT KEY are optional keywords to specify the key that scrolls to the
next page in the INPUT ARRAY or DISPLAY ARRAY state-
ment. The default is [ F3 ].
PREVIOUS KEY are optional keywords to specify the key that scrolls to the
previous page in the INPUT ARRAY or DISPLAY ARRAY state-
ment. 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.
HELP FILE are optional keywords to specify the file that contains pro-
grammer-defined help messages. (Appendix E describes
mkmessage, the help message utility.)
help-file is the pathname, enclosed in quotation ( " ) marks, of the file
containing help messages.
HELP KEY are optional keywords to specify the key that displays help
messages. The default is CTRL-W.
INPUT are optional keywords to specify field attributes that are in
ATTRIBUTE effect when data values are entered.
attribute-list is a list of one or more screen display attributes, or the key-
words FORM or WINDOW.

7-166 INFORMIX-4GL Statement Syntax

OPTIONS

DISPLAY are optional keywords to specify screen attributes that are in

ATTRIBUTE 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 [ + integer ]
LAST [ - integer ]
Here FIRST is the first 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
first 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 field descriptions in the current form file. (See the
“Attributes Syntax” section of Chapter 4.)

INFORMIX-4GL Statement Syntax 7-167

OPTIONS

3. Any default attributes in the syscolatt table of fields linked to

database columns. (See the description of the “The upscol Utility” in
Appendix E.)
4. Any attributes and reserved line positions specified 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 BLUE REVERSE
YELLOW BLACK BLINK
MAGENTA DIM UNDERLINE
RED INVISIBLE FORM
CYAN BOLD WINDOW
GREEN NORMAL
9. The INPUT ATTRIBUTE clause specifies the screen attributes to be used
during a CONSTRUCT, INPUT, or INPUT ARRAY statement when no
attribute-list is specified in those statements or in the specification file of
the current form.
10. Similarly, the DISPLAY ATTRIBUTE clause specifies the screen attributes to
be used during a DISPLAY or DISPLAY ARRAY statement when no
attribute-list is specified in those statements or in the specification file 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 specifies 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 fields 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

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 are required keywords.
REPORT
report-name is the identifier of a report.
expr-list 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

Overview
Use the PREPARE statement to preprocess an SQL statement for later execu-
tion. The SQL statements are listed in Chapter 3.

Syntax
PREPARE statement-id FROM string-spec

Explanation:
PREPARE is a required keyword.
statement-id is an SQL identifier for a statement.
FROM is a required keyword.
string-spec is either a string constant enclosed in quotation marks or a
CHAR type program variable. The string-spec must contain
an SQL statement.

Notes
1. The statement(s) described in string-spec cannot contain program vari-
ables. 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 identifier 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 identifier that you can reference in another source file.

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

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.
display-list is a list of one or more program variables or string constants,
separated by commas.
ATTRIBUTE is a keyword to specify screen display attributes.
(attribute-list) is a list (in parentheses) of one or more screen display
attributes, separated by commas.
FOR is a required keyword.
CHAR is an optional keyword.
variable is the program variable that will contain the value typed in
by the user.
HELP is an optional keyword.
help-number is an integer that identifies the help message for this PROMPT
statement in the help file designated in the OPTIONS
statement.
ON KEY are optional keywords.
key-list is a list of one or more function or CTRL key designations. It
can also include ESCAPE (if you have specified 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

PROMPT

statement is an INFORMIX-4GL statement.

END are keywords to terminate a PROMPT statement (required
PROMPT 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 first 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 specified 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, INFOR-
MIX-4GL executes the statements in the ON KEY clause and sets
int_flag 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 imple-
mentation of UNIX.
6. INFORMIX-4GL terminates PROMPT and passes control to the statements
following an ON KEY clause when the user presses a key specified in key-

7-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 fol-
lowing END PROMPT.
7. The notation for function keys is F1 through F36. The notation for CON-
TROL 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 specifications must appear before the ON KEY
clause, not after it.
9. The first 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 first 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 specified in an
OPTIONS or OPEN WINDOW statement.
13. These keywords can appear in the ATTRIBUTE clause:
WHITE = NORMAL REVERSE
YELLOW = BOLD BLINK
MAGENTA = BOLD UNDERLINE
RED = BOLD
CYAN = DIM
GREEN = DIM
BLUE = DIM
BLACK = INVISIBLE
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 inter-
preted 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 files 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 first 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 first character of the display-list is a blank if you
specify any display attributes.
14. On UNIX systems that use terminfo files rather than termcap, INFOR-
MIX-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

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.
cursor-name is the name of a cursor that has been DECLAREd for an
INSERT statement.
FROM is an optional keyword.
variable-list is a list of program variables, separated by commas, corre-
sponding to the ‘‘?’’ parameters in the PREPAREd INSERT
statement associated with cursor-name.

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 flush the buffer (by executing a series of PUT state-
ments, 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 with-
out closing an insert cursor leaves the buffer unflushed. Rows inserted

INFORMIX-4GL Statement Syntax 7-177

PUT

into the buffer since the last flush are lost. You cannot rely on the end of
program to close the cursor and flush the buffer.
5. The global variables status (whose value is received from SQLCA.SQL-
CODE) 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 unsuccess-
ful in its attempt to insert an entire block of rows into the database, it sets
status to a negative number (specifically, the number of the error mes-
sage) and sets SQLCA.SQLERRD[3] to the number of rows successfully
inserted into the database.
6. Whenever the buffer is flushed, SQLCA.SQLERRD[3] is set to the number
of rows successfully inserted into the database. If an error occurs during
the flushing 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

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 file.

Syntax
RECOVER TABLE table-name

Explanation
RECOVER TABLE are required keywords.
table-name is the name of the table you want to recover.

Notes
1. Once you have recovered the table, use the DROP AUDIT statement to
remove the contents of the audit trail file. Run the CREATE AUDIT state-
ment to start a new audit trail file, 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 finds 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

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 is the required name of the table containing the column
whose name is to be changed.
oldcolumn is the name of the column to be renamed.
TO is a required keyword.
newcolumn is the new name to be assigned to the column. The
newcolumn must satisfy the requirements for an SQL
identifier, and cannot duplicate another column name in
the table.

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

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.
oldname is the current name of the table to be renamed.
TO is a required keyword.
newname is the new name that you want to assign to the table.

Notes
1. In a non-MODE ANSI database, the newname identifier 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 privi-
lege, or have been granted ALTER permission on the table.
3. You can specify owner.oldname in a RENAME TABLE statement, but a com-
pile-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 SMALLINT,
order_num INTEGER,
quantity SMALLINT,
stock_num SMALLINT,
manu_code CHAR(4),
total_price 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

Overview
Use the REPORT routine to provide the format specifications 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 identifier.
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 vari-
ables 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

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.
expr-list is an optional list of one or more expressions, separated by
commas.

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

Overview
Use the REVOKE statement to remove another user’s 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.
tab-privilege is one or more of the following table-level access privileges,
separated by commas:
ALTER Adds or deletes columns or modifies
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
ON is a required keyword.
table-name is the name of the table for which you are revoking access
privileges.
db-privilege 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.
FROM is a required keyword.

INFORMIX-4GL Statement Syntax 7-187

REVOKE

PUBLIC is the keyword to revoke access privilege from all users.

user-list 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.

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 specific col-
umns, you cannot revoke these privileges column by column. If you
revoke UPDATE or SELECT privileges from a user, INFORMIX-4GL auto-
matically revokes all UPDATE and SELECT privileges that you have ever
granted to that user for table-name. You can then re-grant privileges for
specific columns.
6. Only a DBA recipient can revoke the DBA privilege from another recipi-
ent. 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 privi-
leges 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

Overview
Use the ROLLBACK WORK statement to undo all modifications 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

Overview
Use the ROLLFORWARD DATABASE statement to cause INFORMIX-4GL to
apply the transactions registered in the transaction log file 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

Overview
Use the RUN statement to execute a system program.

Syntax
RUN command-line [ RETURNING integer-variable
| WITHOUT WAITING ]

Explanation
RUN 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 char-
acter 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.

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 nei-
ther 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 { field-list | screen-record. * } [ , . . . ]
{ UP | DOWN } [ BY integer ]

Explanation
SCROLL is a required keyword.
field-list is a list of one or more screen field names, separated by
commas.
screen-record is the name of a screen record.
UP is an optional keyword indicating that the data on the screen
should move upwards.
DOWN is an optional keyword indicating that the data on the screen
should move downwards.
BY is an optional keyword.
integer is an INTEGER constant or variable.

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

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

Overview
Use the SET EXPLAIN statement to record how the query processor is access-
ing the database when executing a query.

Syntax
SET EXPLAIN { ON | OFF }

Explanation
SET EXPLAIN are required keywords.
ON is a keyword to enable the EXPLAIN facility.
OFF 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 file 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 iden-
tifies the type of access and the column(s) that serves as a filter, including
whether the filtering is through an index. The following table-access
types are available:
SEQUENTIAL SCAN reads rows in sequence.
INDEX PATH scans one or more indexes.
AUTOINDEX PATH creates a temporary index.
3. The name of the owner precedes each table name in the output file.

7-194 INFORMIX-4GL Statement Syntax

SET EXPLAIN

Examples
The following example shows an sqexplain.out output file 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 file 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 )

Overview
Use the SET LOCK MODE statement to determine whether subsequent INFOR-
MIX-4GL calls wait for a locked row to become unlocked.

Syntax
SET LOCK MODE TO [ NOT ] WAIT

Explanation
SET LOCK MODE are required keywords.
TO is a required keyword.
NOT is an optional keyword.
WAIT 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 indefinitely.
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 state-
ment 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

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.
integer-expr is an expression that evaluates to INTEGER type.

Note
The SLEEP statement causes the program to suspend operation for integer-
expr seconds.

Example
SLEEP 4

INFORMIX-4GL Statement Syntax 7-199

START DATABASE

Overview
Use the START DATABASE statement to start a new transaction log file.

Syntax
START DATABASE database-name WITH LOG IN "pathname" [ MODE ANSI ]

Explanation
START DATABASE are required keywords.
database-name is the name of a database.
WITH LOG IN are required keywords.
pathname is the full pathname, enclosed in quotation ( " ) marks,
of the transaction log file.
MODE ANSI are optional keywords to convert the database to
MODE ANSI.

Notes
1. The START DATABASE statement can perform these tasks:
• Change the name of your transaction log file.
• 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 prefix. 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 state-

ment, 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 char-
acter 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 { filename | PRINTER | PIPE program } ]

Explanation
START REPORT are required keywords.
report-name is the identifier of a report.
TO is an optional keyword.
filename is either a CHAR type variable or a quoted string constant
containing the name of a system file.
PRINTER is an optional keyword.
PIPE is an optional keyword.
program is either a CHAR variable or a string constant containing the
command line for a system 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 state-
ment in the OUTPUT section of report-name.
3. If you indicate filename, INFORMIX-4GL puts the report output there.
4. If you use the TO PRINTER option, INFORMIX-4GL sends the report out-
put 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 set-
ting 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

Overview
Use the UNLOAD statement to write the data from a table to an ASCII file.

Syntax
UNLOAD TO "pathname" [ DELIMITER "char" ] SELECT-statement

Explanation
UNLOAD TO are required keywords.
pathname is a quoted string or a character variable that evaluates to
the pathname of the file in which to store the database
table.
DELIMITER is an optional keyword to indicate that the following char
separates data fields in the file.
char is a single character that serves as the delimiter between
fields. The char must appear in quotation marks.
SELECT-statement is a SELECT statement that retrieves the data to be written
to a file.

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 char-
acter 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 automat-
ically escapes it with a backslash to prevent interpretation as a special
character. (Backslashes are automatically stripped when the field 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, SMALL-
FLOAT, 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 field digits and delimiters. No type specification or qualifiers
are output. INFORMIX-4GL uses the following pattern: yyyy-mm-dd
hh:mi:ss.fff, omitting fields 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 file.

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 INFOR-
MIX-OnLine Programmer’s Manual for more information.

7-204 INFORMIX-4GL Statement Syntax

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.
table-name is the name of the table you want to unlock.

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

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.
table-name is the name of the table that contains the row(s) that you
want to update.
SET is a required keyword.
column-name is the name of a column you want to update.
expr is any combination of column names, constants, program
variables, arithmetic operators, or an SQL subquery that
returns a single row of one value.
column-list 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.)
expr-list 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 sin-
gle row of multiple values.
record-name is the name of a program variable of type RECORD.
WHERE is an optional keyword.
condition 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

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.
cursor-name is the SQL identifier of a previously DECLAREd cursor.

Notes
1. The expr can be a SELECT statement in parentheses that adheres to stan-
dard 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 ROLL-
BACK 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 oper-
ation 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 data-
base 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", "Marie’s 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

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.
table-name is the name of the table for which you want the
statistics updated.

Notes
1. UPDATE STATISTICS is effective only when there is a current database.
2. INFORMIX-4GL uses the data generated by UPDATE STATISTICS to opti-
mize searching strategy. When you have modified a table extensively, use
UPDATE STATISTICS to improve the efficiency 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 INFORMIX-

OnLine Programmer’s Manual for more information.

7-210 INFORMIX-4GL Statement Syntax

VALIDATE

Overview
Use the VALIDATE statement to determine whether values in a list of vari-
ables conform to the allowed ranges of values in syscolval for a correspond-
ing list of columns.

Syntax
VALIDATE variable-list LIKE column-list

Explanation
VALIDATE is a required keyword.
variable-list is a list of one or more variables, separated by commas.
LIKE is a required keyword.
column-list is a list of column names, preceded by table names and sep-
arated by commas.

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 prefix to designate the column names.
3. In a MODE ANSI database, the name of a table is qualified 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 prefix 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 sin-
gle syscolval table that specifies acceptable values or ranges of values for
any or all columns in the database. The VALIDATE statement compares
variable-list with the limitations specified 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, INFOR-
MIX-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 prefix 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

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 is a required keyword.
ERROR 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.
WARNING is a keyword to test for a warning (SQLAWARN[1] is set to W)
after each 4GL statement. Its synonym is SQLWARNING.
NOT FOUND are keywords to test whether a FETCH is attempted beyond
the first or last row in the active set, or if no more rows satisfy
the current SELECT statement (status=100).
GOTO is an optional keyword. Its synonym GO TO conforms to the
ANSI standard for SQL syntax.
: is an optional prefix to label, and conforms to the ANSI stan-
dard for SQL syntax.
label is a statement label to which program control transfers when
the specified exceptional condition occurs.
CALL is an optional keyword.
function-name is the name of a function to which program control transfers
when the exceptional condition occurs.
CONTINUE is an optional keyword, instructing INFORMIX-4GL to take
no action. You can use this option to turn off a previously
specified option.
STOP is an optional keyword, instructing INFORMIX-4GL to exit
from the program immediately.

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 specified in the DATABASE statement that
precedes the MAIN program block or the first FUNCTION or REPORT rou-
tine 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 WHEN-
EVER ERROR is CONTINUE. Otherwise, the default is STOP. No DATABASE
or START DATABASE statement in a function has any effect on the WHEN-
EVER 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 file in which it occurs, and
from its position in the file to the next WHENEVER statement for the same
exception condition in the same file. The scope extends to the end of the
file, if you do not specify more WHENEVER statements for the same
exception condition.
5. INFORMIX-4GL provides useful information (like source-file line num-
bers where an error has occurred) when it terminates a program because
of an error. You may want to allow errors to occur during program devel-
opment 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 specified 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. Cer-
tain errors always terminate the program, and others result in action by
INFORMIX-4GL prior to the action specified by WHENEVER. (If you also
have the INFORMIX-4GL Interactive Debugger, however, you can exam-
ine 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 con-
trol, 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

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.
Boolean-expr is an expression that can be either true or false.
statement is an INFORMIX-4GL statement (including another
WHILE statement).
EXIT WHILE is an optional statement.
CONTINUE WHILE is an optional statement.
END WHILE are required keywords that terminate a WHILE
statement.

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 Bool-
ean-expr.
2. The EXIT WHILE statement interrupts the sequence and causes the pro-
gram control to jump to the first statement following the END WHILE
keywords.
3. If Boolean-expr is FALSE on entry to the WHILE statement, program con-
trol 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

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 fol-
lowing 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 con-
cepts are defined 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 identifier.
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
defined 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 col-
umn is column-name[m, n], where you want the mth through the nth char-
acters 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 Operation
= equal to
!= or < > 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 follow-
ing pages. Briefly, 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 tem-
porary 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
defined, 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, INFOR-
MIX-4GL eliminates from this new table all rows that do not meet the con-
ditions of the WHERE clause. This modified 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

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 is a required keyword.
ALL is a keyword that causes INFORMIX-4GL to select all rows
that satisfy the WHERE clause, without eliminating dupli-
cates. This keyword is the default.
DISTINCT is a keyword that causes INFORMIX-4GL to eliminate dupli-
cate rows from the query results.
UNIQUE is a keyword that is synonymous with DISTINCT.
select-list is a list of column names and/or expressions separated by
commas. A column name must be unambiguous; use its
table name as a prefix if there can be confusion.

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 nota-
tion 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 identi-
fier. 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 defined.
6. If you specify an aggregate function and a column in the select-list, the col-
umn 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 defined 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 identifier is prefixed 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 col-
umns 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

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.
variable-list is a list of program variables that should agree in order and
type with the corresponding columns or expressions in the
select-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 discus-

sion 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

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 is a required keyword.
OUTER is an optional keyword.
table-name is the name or synonym of a table or view in which to search
for data.
table-alias is an optional alias for table-name.
(table-expr) is one or more of the options in the preceding syntax,
enclosed in parentheses (for example tab1, outer tab2).

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 discus-
sion of this syntax.
2. In a database created as MODE ANSI, the name of a table or view is qual-
ified 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 prefix 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 identifier. This feature is especially useful when per-
forming 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
specification file. An alias that you define in a form can appear in 4GL
screen interaction statements that reference screen fields 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

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.
condition 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:
• 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 condi-
tions can be preceded by the keyword NOT, in which case the row is selected
only if the condition that NOT qualifies is FALSE.

Syntax
expr rel-op expr

7-228 INFORMIX-4GL Statement Syntax

WHERE Clause

Explanation
expr is an expression.
rel-op 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 is an expression.
NOT is a keyword that indicates that the expression to the left lies
outside the range.
BETWEEN 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 is an expression.
NOT is an optional keyword.
IN is a required keyword.
(value-list) is a list of values (enclosed in parentheses).

Notes
1. The search condition is satisfied when the expression to the left is
included in the list of items. The NOT option produces a search condition
that is satisfied when expr is not in the list of items.
2. The value-list can contain program variables, constants, or the special key-
word constants TODAY, CURRENT, and USER.
3. TODAY is evaluated at execution time. CURRENT is evaluated when a cur-
sor 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 is the name of a column.
NOT is an optional keyword.
LIKE is a required keyword.
string is a pattern of characters enclosed in quotation marks.
ESCAPE is an optional keyword.
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 specified by string. You can use wildcard charac-
ters 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 specified by string.
3. The purpose of the ESCAPE clause is to permit the specification of an
underscore ( _ ) or the percent sign ( % ) in string, and to avoid their inter-
pretation 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"
finds 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, manufacturer’s 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 is the name of a column.
NOT is an optional keyword.
MATCHES is a required keyword.
string is a pattern of characters enclosed in quotation marks.
ESCAPE is an optional keyword.
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 specified by string. You can use the following
wildcard characters in place of other characters in the string:
* matches zero or more characters
? matches any single character

7-232 INFORMIX-4GL Statement Syntax

WHERE Clause

[...] matches any of the enclosed characters, including character

ranges as in [a-z]. A caret ( ^ ) as the first 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 significance 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 specified 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 specification of a ques-
tion 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 sin-
gle 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 first 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 the name of a column.
IS NULL are required keywords.
NOT 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.
table1 is the name or synonym of one of the tables or views in the
join.
table2 is the name or synonym of the other table or view in the join.
WHERE is a required keyword.
condition is any of the comparison conditions that involves columns
from both table1 and table2.

Notes
1. When columns from different tables have the same name, you must dis-
tinguish them by prefixing the table identifier and a period, in the format
table.column.
2. In a database created as MODE ANSI, the name of a table is qualified 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 prefix 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 specifies 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 first and last names of the cus-
tomer’s representative for each order.
This example specifies 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
identified with the stock number and manufacturer code.
This example specifies 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 finds 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 specifies 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.
expr is an expression.
rel-op is a relational operator.
ALL is a keyword to specify that the subquery can return zero, one, or
more values, and that the search condition is TRUE if the compar-
ison is TRUE for each of the values returned. If the subquery
returns no value, the search condition is TRUE.
ANY is a keyword to specify that the subquery can return zero, one, or
more values and that the search condition is TRUE if the compari-
son is TRUE for at least one of the values returned. If the subquery
returns no value, the search condition is FALSE.
SOME is a synonym for ANY.

INFORMIX-4GL Statement Syntax 7-237

WHERE Clause

IN is a keyword that asks whether expr is among the values returned

by the following SELECT-statement.
EXISTS is a keyword that asks whether any rows are returned by the fol-
lowing SELECT-statement. The search condition is TRUE if the sub-
query returns one or more rows.
NOT is an optional keyword that reverses the truth value of the search
condition. Rows are selected if the WHERE condition is FALSE.

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 num-
ber if the subquery returns other than a single value.
2. The specification expr IN ( SELECT-statement )
is equivalent to expr = ANY ( SELECT-statement ).
3. The specification 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

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.
group-list is a column name or a list of column names, separated by
commas, that determines the group. The query result con-
tains a single row for each set of rows that satisfies the
WHERE clause and contains a unique value or set of values
in the column or columns indicated by 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 inte-
gers 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

Overview
Use the HAVING clause to apply one or more qualifying conditions to groups.

Syntax
HAVING condition

Explanation
HAVING is a required keyword.
condition is a condition, as if defined for a WHERE clause.

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 col-
umn 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

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.
column-name is the name of a column by which you want to sort the query
results.
ASC is a keyword that specifies that the results should be in
ascending order (smallest value first, largest last). ASC is the
default.
DESC is a keyword that specifies that the results should be in
descending order (largest value first).

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 asso-
ciate 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

CORRECT: SELECT *
FROM orders
ORDER BY order_date

INCORRECT: SELECT order_date, ship_date

FROM orders
ORDER BY customer_num
In the first 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 first level of sorting is based on the lname col-
umn, and the second level is based on the fname column.

7-244 INFORMIX-4GL Statement Syntax

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.
table-name is the SQL identifier that you assign to the temporary table.
WITH NO LOG are optional keywords to prevent logging of temporary
tables.

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 select-
list. 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

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 is a keyword that selects all rows from both queries, removes
duplicates, and returns what is left.
ALL 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 identifier.

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 first
SELECT statement.
• If you use an ORDER BY clause, it must follow the last SELECT state-
ment, and you must refer by integer, not by identifier, 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 definition of a view.
5. The column names (or display labels) of the resulting table are the same
as those from the first SELECT statement.
6. You can put the results of a UNION into a temporary table by putting an
INTO TEMP clause in the final SELECT statement.

Example
The following example selects those items (identified 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

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 Length Date Datetime
Functions Functions Functions Functions
COUNT(*) LENGTH( ) DATE( ) CURRENT
SUM( ) DAY( ) EXTEND( )
AVG( ) MDY( )
MAX( ) MONTH( )
MIN( ) WEEKDAY( )
YEAR( )
These functions are defined 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

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 Function
COUNT (*) returns the number of rows that satisfy the
WHERE clause.
COUNT ( DISTINCT x) returns the number of different values in col-
umn x from rows that satisfy the WHERE
clause.
SUM ( [ ALL | DISTINCT ] x) 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 val-
ues in column x.
AVG ( [ ALL | DISTINCT ] 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.
MAX ( [ ALL | DISTINCT ] x) returns the largest value in column x from a
row that satisfies the WHERE clause. Default
is ALL.
MIN ( [ ALL | DISTINCT ] x) returns the lowest value in column x from a
row that satisfies the WHERE clause. Default
is ALL.

Notes
1. In the functions SUM(x), AVG(x), MAX(x), and MIN(x), x can be an expres-
sion 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

satisfies the WHERE clause. The expression can not contain another aggre-
gate 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 elimi-
nate 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 val-
ues, MAX (x) returns 4, and MIN (x) returns 2.

7-250 INFORMIX-4GL Statement Syntax

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 Programmer’s Manual for more information.

INFORMIX-4GL Statement Syntax 7-251

DATE( )

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

Syntax
DATE ( expr )

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

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( )

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 com-
pare column values to the current day of the month.
WHERE DAY(ord_date) > DAY(CURRENT)

INFORMIX-4GL Statement Syntax 7-253

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 )

Notes
The value of expr3 cannot be the abbreviation for the year. For example, 89 is
a year in the first century.

7-254 INFORMIX-4GL Statement Syntax

MONTH( )

Overview
The MONTH( ) function returns an integer corresponding to the month por-
tion 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( )

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.
time-expr is a required expression of type DATE or DATETIME.

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( )

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 specifies rows in which the ship_date is earlier than the
beginning of the current year.

INFORMIX-4GL Statement Syntax 7-257

CURRENT

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

Syntax
CURRENT [ first 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 first qualifier must specify a field that is more significant than or equal
to the last qualifier.
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 specific point in the execution of the 4GL
statement.
6. If no first TO last qualifiers are specified, the default qualifiers are YEAR
TO FRACTION(3).

7-258 INFORMIX-4GL Statement Syntax

CURRENT

7. The following qualifiers are valid:

Identifier Qualified Data
YEAR A number of years.
MONTH A number of months.
DAY A number of days.
HOUR A number of hours.
MINUTE A number of minutes.
SECOND A number of seconds.
FRACTION (n) A decimal fraction of a second with n (up to five) 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( )

Overview
The EXTEND function adjusts the precision of a DATETIME or DATE value.

Syntax
EXTEND ( value [ , first TO last ] )

Explanation
EXTEND is a required keyword.
value is a DATETIME or DATE type column name, variable, or
expression.
first is an optional qualifier that specifies the first field in the result.
(See Note 5.)
TO is a required keyword if you include first and last qualifiers.
last is an optional qualifier that specifies the last field in the result.
(See Note 6.)

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 first TO last qualifiers are specified, the default qualifiers are YEAR
TO FRACTION(3).
3. The first qualifier must specify a field that is more significant than or equal
to the last qualifier.
4. If the value contains fields not specified by the qualifiers, the unwanted
fields are discarded.
5. If the first qualifier specifies a field to the left of (that is, more significant
than) what exists in value, the new fields are filled with values returned
by the CURRENT function.

7-260 INFORMIX-4GL Statement Syntax

EXTEND( )

6. If the last qualifier specifies a field to the right of (that is, less significant
than) what exists in value, the new fields are filled in with constant values.
A missing MONTH or DAY is filled in with 1, and the missing fields HOUR
to FRACTION are filled in with 0.
7. The following qualifiers are valid:
Identifier Qualified Data
YEAR A number of years.
MONTH A number of months.
DAY A number of days.
HOUR A number of hours.
MINUTE A number of minutes.
SECOND A number of seconds.
FRACTION (n) A decimal fraction of a second with n (up to five) digits
of precision. The default precision is three digits
(thousandths of a second).

8. If an INTERVAL value includes a field that is not present in a DATETIME

value, you cannot combine the two values with the addition ( + ) or sub-
traction ( - ) operators. Similarly, you cannot add or subtract a DATE
value and an INTERVAL whose last qualifier 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
fields from a column that contains YEAR, MONTH, and DAY data. In this
instance the YEAR field 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 qualifier is larger than MINUTE. Then the
EXTEND function is required in the following statement, because the
INTERVAL operand includes a field (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 qualifiers are specified as arguments, the EXTEND function returns

a DATETIME value with the default precision YEAR to FRACTION(3). The
WHERE clause in this example specifies 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 documen-
tation of other Informix products. The stores database is not
MODE ANSI.

This appendix contains five sections:

• The first 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 identi-
fied and classified 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 informa-
tion from multiple tables.
• The fourth section shows the data contained in each
table of the stores database.
Structure of the Tables

• The final section contains the form specifications, INFORMIX-4GL source

code modules, and help message source code for the demonstration
application.
If you have modified 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 files there. It also copies all the dem-
onstration programs, forms, and help files into the current directory.

Structure of the Tables

The stores database contains information about a fictitious 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 store’s name, address, and telephone number, and
the name of its representative. The customer table has the following columns:
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)
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 dis-
tributor. This information includes the order number, the date when the
order was made, the customer number, shipping instructions, the customer’s
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 serial(1001)
order_date date
customer_num integer
ship_instruct char(40)
backlog char(1)
po_num char(10)
ship_date date
ship_weight decimal(8,2)
ship_charge money(6)
paid_date 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 smallint
order_num integer
stock_num smallint
manu_code char(3)
quantity smallint
total_price money(8)
The order_num column has an index that allows duplicate values. A multi-
ple-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 fifteen 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 smallint
manu_code char(3)
description char(15)
unit_price money(6)
unit char(4)
unit_descr 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 five manufacturers whose sporting goods are handled
by the distributor is kept in the manufact table. Each row contains a manu-
facturer’s identifying code and name. The columns in the manufact table are
as follows:
manu_code char(3)
manu_name 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 fifty states
of the United States. It includes two columns:
code char(2)
sname char(15)
The code column is indexed as unique.

A-4 Demonstration Database and Application

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 item_num
order_num order_num stock
customer order_date stock_num stock_num manufact
customer_num customer_num manu_code manu_code manu_code
fname ship_instruct quantity description manu_name
lname backlog total_price unit_price
company po_num unit
address1 ship_date unit_descr
address2 ship_weight
state city ship_charge
code state paid_date
sname zipcode
phone
Figure A-1 Tables in the stores Database

Join Columns That Link the Database

The tables of the stores database are linked together by join columns, which
are identified in this section. You can use them to retrieve and display infor-
mation 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 fname lname customer table

101 Ludwig Pauli (detail)
102 Carole Sadler
103 Philip Currie
104 Anthony Higgins

order_num order_date customer_num orders table

1001 01/20/1989 104 (detail)
1002 06/01/1989 101
1003 10/12/1989 104
1004 04/12/1989 106
Figure A-2 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 customer’s name, com-
pany, address, and telephone number. For example, the row with informa-
tion about Anthony Higgins contains the number 104 in the customer_num
column.
The orders table also contains a customer_num column that stores the num-
ber 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 Higgins’s 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 con-
tains an identification 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 order_date customer_num

orders table
1001 01/20/1989 104 (detail)
1002 06/01/1989 101
1003 10/12/1989 104
1004 04/12/1989 106

item_num order_num stock_num manu_code

items table
1 1001 1 HRO (detail)
1 1002 4 HSK
2 1002 3 HSK
1 1003 9 ANZ
2 1003 8 ANZ
3 1003 5 ANZ
Figure A-3 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 exam-
ple, 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 order_num stock_num manu_code

items table
1 1001 1 HRO (detail)
1 1002 4 HSK
2 1002 3 HSK
1 1003 9 ANZ
2 1003 8 ANZ
3 1003 5 ANZ
1 1004 1 HRO

stock_num manu_code description

stock table
1 HRO baseball glove (detail)
1 HSK baseball glove
1 SMT baseball glove
Figure A-4 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 manu_code description

stock table
1 HRO baseball glove (detail)
1 HSK baseball glove
1 SMT baseball glove
2 HRO baseball

manu_code manu_name
manufact table
NRG Norge (detail)
HSK Husky
HRO Hero
Figure A-5 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 A-
6.

customer_num fname lname ... state customer table

101 Ludwig Pauli ... CA (detail)
102 Carole Sadler ... CA
103 Philip Currie ... CA

code sname state table

(detail)
AK Alaska
AL Alabama
AR Arkansas
AZ Arizona
CA California
Figure A-6 Tables Joined by the State-Code Column

Joining lets you rearrange your view of a database whenever you want. It
provides flexibility that lets you create new relationships between tables
without redesigning the database. You can easily expand the scope of a data-
base 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 figures 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

customer_num fname lname company address1 address2 city state zip code phone

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
103 Philip Currie Phil’s Sports 654 Poplar P. O. Box 3498 Palo Alto CA 94303 415-328-4543

Demonstration Database and Application

104 Anthony Higgins Play Ball! East Shopping Cntr. 422 Bay Road Redwood City CA 94026 415-368-1100
105 Raymond Vector Los Altos Sports 1899 La Loma Drive Los Altos CA 94022 415-776-3249
106 George Watson Watson & Son 1143 Carver Place Mountain View CA 94063 415-389-8789
Data in the stores Database

107 Charles Ream Athletic Supplies 41 Jordan Avenue Palo Alto CA 94304 415-356-9876
108 Donald Quinn Quinn’s Sports 587 Alvarado Redwood City CA 94063 415-544-8729
109 Jane Miller Sport Stuff Mayfair Mart 7345 Ross Blvd. Sunnyvale CA 94086 408-723-8789
110 Roy Jaeger AA Athletics 520 Topaz Way Redwood City CA 94062 415-743-3611
111 Frances Keyes Sports Center 3199 Sterling Court Sunnyvale CA 94085 408-277-7245
112 Margaret Lawson Runners & Others 234 Wyandotte Way Los Altos CA 94022 415-887-7235
113 Lana Beatty Sportstown 654 Oak Grove Menlo Park CA 94025 415-356-9982
114 Frank Albertson Sporting Place 947 Waverly Place Redwood City CA 94062 415-886-6677
115 Alfred Grant Gold Medal Sports 776 Gary Avenue Menlo Park CA 94025 415-356-1123
116 Jean Parmelee Olympic City 1104 Spinosa Drive Mountain View CA 94040 415-534-8822
117 Arnold Sipes Kids Korner 850 Lytton Court Redwood City CA 94063 415-245-4578
118 Dick Baxter Blue Ribbon Sports 5427 College Oakland CA 94609 415-655-0011
Data in the stores Database

items Table

item_num order_num stock_num manu_code quantity total_price

1 1001 1 HRO 1 250.0
1 1002 4 HSK 1 960.0
2 1002 3 HSK 1 240.0
1 1003 9 ANZ 1 20.0
2 1003 8 ANZ 1 840.0
3 1003 5 ANZ 5 99.0
1 1004 1 HRO 1 960.0
2 1004 2 HRO 1 126.0
3 1004 3 HSK 1 240.0
4 1004 1 HSK 1 800.0
1 1005 5 NRG 10 280.0
2 1005 5 ANZ 10 198.0
3 1005 6 SMT 1 36.0
4 1005 6 ANZ 1 48.0
1 1006 5 SMT 5 125.0
2 1006 5 NRG 5 190.0
3 1006 5 ANZ 5 99.0
4 1006 6 SMT 1 36.0
5 1006 6 ANZ 1 48.0
1 1007 1 HRO 1 250.0
2 1007 2 HRO 1 126.0
3 1007 3 HSK 1 240.0
4 1007 4 HRO 1 480.0
5 1007 7 HRO 1 600.0
1 1008 8 ANZ 1 840.0
2 1008 9 ANZ 5 100.0
1 1009 1 SMT 1 450.0
1 1010 6 SMT 1 36.0
2 1010 6 ANZ 1 48.0
1 1011 5 ANZ 5 99.0
1 1012 8 ANZ 1 840.0
2 1012 9 ANZ 10 200.0
1 1013 5 ANZ 1 19.8
2 1013 6 SMT 1 36.0
3 1013 6 ANZ 1 48.0
4 1013 9 ANZ 2 40.0
1 1014 4 HSK 1 960.0
2 1014 4 HRO 1 480.0
1 1015 1 SMT 1 450.0

Demonstration Database and Application A-11

A-12
orders Table

order_num order_date customer_num ship_instruct backlog po_num ship_date ship_weight ship_charge paid_ date

1001 01/20/89 104 ups n B77836 02/01/89 20.40 10.00 03/22/89

1002 06/01/89 101 po on box; n 9270 06/06/89 50.60 15.30 07/03/89
deliver back door only
1003 10/12/89 104 via ups n B77890 10/13/89 35.60 10.80 11/04/89
1004 04/12/89 106 ring bell twice y 8006 04/30/89 95.80 19.20

Demonstration Database and Application

1005 12/04/89 116 call before delivering n 2865 12/19/89 80.80 16.20 12/30/89
1006 09/19/89 112 after 10 am y Q13557 70.80 14.20
Data in the stores Database

1007 03/25/89 117 n 278693 04/23/89 125.90 25.20

1008 11/17/89 110 closed Monday y LZ230 12/06/89 45.60 13.80 12/21/89
1009 02/14/89 111 door next to supersaver n 4745 03/04/89 20.40 10.00 04/21/89
1010 05/29/89 115 deliver 776 Gary n 429Q 06/08/89 40.60 12.30 07/22/89
if no answer
1011 03/23/89 104 ups n B77897 04/13/89 10.40 5.00 06/01/89
1012 06/05/89 117 n 278701 06/09/89 70.80 14.20
1013 09/01/89 104 via ups n B77930 09/18/89 60.80 12.20 10/10/89
1014 05/01/89 106 ring bell, kick door loudly n 8052 05/10/89 40.60 12.30 07/18/89
1015 07/10/89 110 closed Mon n MA003 08/01/89 20.60 6.30 08/31/89
Data in the stores Database

stock Table
stock_num manu_code description unit_price unit unit_descr
1 HRO baseball gloves 250.00 case 10 gloves/case
1 HSK baseball gloves 800.00 case 10 gloves/case
1 SMT baseball gloves 450.00 case 10 gloves/case
2 HRO baseball 126.00 case 24/case
3 HSK baseball bat 240.00 case 12/case
4 HSK football 960.00 case 24/case
4 HRO football 480.00 case 24/case
5 NRG tennis racquet 28.00 each each
5 SMT tennis racquet 25.00 each each
5 ANZ tennis racquet 19.80 each each
6 SMT tennis ball 36.00 case 24 cans/case
6 ANZ tennis ball 48.00 case 24 cans/case
7 HRO basketball 600.00 case 24/case
8 ANZ volleyball 840.00 case 24/case
9 ANZ volleyball net 20.00 each each

manufact Table
manu_code manu_name

ANZ Anza
HSK Husky
HRO Hero
NRG Norge
SMT Smith

Demonstration Database and Application A-13

Data in the stores Database

state Table

code sname code sname

AK Alaska MT Montana
AL Alabama NB Nebraska
AR Arkansas NC North Carolina
AZ Arizona ND North Dakota
CA California NH New Hampshire
CO Colorado NJ New Jersey
CT Connecticut NM New Mexico
DE Delaware NV Nevada
FL Florida NY New York
GA Georgia OH Ohio
HI Hawaii OK Oklahoma
IA Iowa OR Oregon
ID Idaho PA Pennsylvania
IL Illinois RI Rhode Island
IN Indiana SC South Carolina
KS Kansas SD South Dakota
KY Kentucky TN Tennessee
LA Louisiana TX Texas
MA Massachusetts UT Utah
MD Maryland VA Virginia
ME Maine VT Vermont
MI Michigan WA Washington
MN Minnesota WI Wisconsin
MO Missouri WV West Virginia
MS Mississippi WY Wyoming

A-14 Demonstration Database and Application

The Demonstration Application

The following pages contain the form specifications, INFORMIX-4GL source
code modules, and help message source file for the demo4.4ge demonstra-
tion application. The application is not complete, and some of the functions
called by the menus are merely ‘‘dead ends.’’
File Name Description
custform.per Form for displaying customer information
orderform.per Form for entering an order
state_list.per Form for displaying a list of states
stock_sel.per Form for displaying a list of stock items
d4_globals.4gl Module containing global definitions
d4_main.4gl Module containing MAIN routine
d4_cust.4gl Module handling the Customer option
d4_orders.4gl Module handling the Orders option
d4_stock.4gl Module handling the Stock option
d4_report.4gl Module handling the Report option
d4_demo.4gl Module handling hidden sample source code option
helpdemo.src Source file for help messages

custform.per
DATABASE stores

SCREEN
{

Customer Form

Number :[f000 ]
Owner Name :[f001 ][f002 ]
Company :[f003 ]
Address :[f004 ]
[f005 ]
City :[f006 ] State:[a0] Zipcode:[f007 ]
Telephone :[f008 ]

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";

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 = orders.order_num;
f010 = orders.order_date, DEFAULT = TODAY;
f011 = orders.po_num;
f012 = orders.ship_instruct;

f013 = items.item_num, NOENTRY;

f014 = items.stock_num;
a1 = items.manu_code, UPSHIFT;
f015 = stock.description, NOENTRY;
f016 = items.quantity;
f017 = stock.unit_price, NOENTRY;
f018 = items.total_price, NOENTRY;
f019 = 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] [f000 ]
[a0] [f000 ]
[a0] [f000 ]
[a0] [f000 ]
[a0] [f000 ]
[a0] [f000 ]
[a0] [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 ][f021 ][f022 ][f023 ]
[f018][f019][f020 ][f021 ][f022 ][f023 ]
[f018][f019][f020 ][f021 ][f022 ][f023 ]
}

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)

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

LET pa_curr = arr_curr()

LET pa_total = arr_count()
LET sc_curr = scr_line()
LET sc_total = 4
FOR 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

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 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,
file_name CHAR(20),
msg CHAR(40)

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 LIKE customer.customer_num,
fname LIKE customer.fname,
lname LIKE customer.lname,
company LIKE customer.company,
order_num LIKE orders.order_num,
order_date LIKE orders.order_date,
ship_date LIKE orders.ship_date,
paid_date LIKE orders.paid_date,
total_price LIKE items.total_price
END RECORD,
file_name CHAR(20),
msg CHAR(50)

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 LIKE customer.customer_num,
fname LIKE customer.fname,
lname LIKE customer.lname,
company LIKE customer.company,
order_num LIKE orders.order_num,
order_date LIKE orders.order_date,
ship_date LIKE orders.ship_date,
paid_date LIKE orders.paid_date,
total_price LIKE items.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 "$$$$,$$$,$$$.&&"

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 Add new customers to the database

o Locate customers in the database
o Update customer files
o Remove customers from the database

.102
The Orders option presents you with a menu that allows you to:

o Enter a new order and print an invoice

o Update an existing order
o Look up and display orders
o Remove orders from the database

.103
The Stock option presents you with a menu that allows you to:

o Add new items to the list of stock

o Look up and display stock items
o Modify current stock descriptions and values
o Remove items from the list of stock

.104
The Reports option presents you with a menu that allows you to:

o Select and print mailing labels sorted by zip code

o Print a report of current accounts receivable
o Print a report of backloged orders
o Print a list of current stock available
o 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 Literal values
o A range of values (separated by ":")
o A list of values (separated by "|")
o Relational operators (for example ">105")
o 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) who’s 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 F1 Insert new line in the screen array

o F2 Remove the current line from the screen array
o F3 Page down one page in the screen array
o F4 Page up one page in the screen array
o ESC Exit input array
o CTRL-B 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.
o etc... The arrow-keys, and the standard field editing keys
are available

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 customer’s company.

.1003
The second section following the Name label should contain the last name of the
contact person at the customer’s company.

.1004
This field should contain the name of the customer’s 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 address of
the customer.

.1008
Enter the two-character code for the desired state. If no code is entered, or
the entered code is not in the program’s 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 customer’s 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:
B
systables describes database tables.
syscolumns describes columns in tables.
sysindexes describes indexes on columns.
systabauth identifies table-level privileges.
syscolauth identifies column-level privileges.
sysdepend describes how views depend on tables.
syssynonyms lists synonyms for tables.
sysusers identifies database-level privileges.
sysviews defines views.
sysconstraints records constraints placed on database
tables.
syssyntable used for mapping of synonyms.
The following list gives a brief description of the system
catalogs.
The SYSTABLES Catalog

The SYSTABLES Catalog

Column
Name Type Explanation
tabname char(18) name of table
owner char(8) owner of table
dirpath char(64) directory path for the table file
tabid serial internal table identifier
rowsize smallint row size
ncols smallint number of columns
nindexes smallint number of indexes
nrows integer number of rows
created date date created
version integer table version number
tabtype char(1) table type (T = table, V = view, S = synonym)
audpath char(64) audit filename (full pathname)

Index
Name Type Columns
tabname unique tabname, owner
tabid unique tabid

The SYSCOLUMNS Catalog

Column
Name Type Explanation
colname char(18) column name
tabid integer table identifier
colno smallint column number
coltype smallint column type
collength smallint column length (physical)

Index
Name Type Columns
column unique tabid, colno

B-2 System Catalogs

The SYSINDEXES Catalog

Column
Name Type Explanation
idxname char(18) index name
owner char(8) owner of index
tabid integer table identifier
idxtype char(1) index type (U = unique, D = dupls)
clustered char(1) clustering
part1 smallint column number
part2 smallint column number
part3 smallint column number
part4 smallint column number
part5 smallint column number
part6 smallint column number
part7 smallint column number
part8 smallint column number

Index
Name Type Columns
idxtab dupls tabid
idxname unique idxname, tabid

The SYSTABAUTH Catalog

Column
Name Type Explanation
grantor char(8) grantor of permission
grantee char(8) grantee (receiver) of permission
tabid integer table identifier
tabauth char(7) authorization type

Index
Name Type Columns
tabgtor unique tabid, grantor, grantee
tabgtee dupls tabid, grantee

The SYSCOLAUTH Catalog

Column
Name Type Explanation
grantor char(8) grantor of permission
grantee char(8) grantee (receiver) of permission
tabid integer table identifier
colno smallint column number
colauth char(2) authorization type

System Catalogs B-3

The SYSDEPEND Catalog

Index
Name Type Columns
colgtor unique tabid, grantor, grantee, colno
colgtee dupls tabid, grantee

The SYSDEPEND Catalog

Column
Name Type Explanation
btabid integer tabid of base table or view
btype char(1) base object type (table or view)
dtabid integer tabid of dependent table
dtype char(1) dependent object type (only view now)

Index
Name Type Columns
btabid dupls btabid
dtabid dupls dtabid

The SYSSYNONYMS Catalog

Column
Name Type Explanation
owner char(8) user name of owner
synonym char(18) synonym identifier
created date date synonym created
tabid integer table identifier

Index
Name Type Columns
synonym unique owner, synonym
syntabid dupls tabid

The SYSUSERS Catalog

Column
Name Type Explanation
username char(8) user login identifier
usertype char(1) D = DBA, R = RESOURCE, C = CONNECT
priority smallint reserved for future use
password char(8) reserved for future use

Index
Name Type Columns
users unique username

B-4 System Catalogs

The SYSVIEWS Catalog

Column
Name Type Explanation
tabid integer table identifier
seqno smallint sequence number
viewtext char(64) portion of SELECT statement

Index
Name Type Columns
view unique tabid, seqno

The SYSCONSTRAINTS Catalog

Column
Name Type Explanation
constrid serial reserved for future use
constrname char(18) constraint identifier
owner char(8) user name of owner
tabid integer table identifier
constrtype char(1) reserved for future use
idxname char(18) index name

Index
Name Type Columns
constrname unique constrname, owner
constrtabid dupls tabid
constrid unique constrid

The SYSSYNTABLE Catalog

Column
Name Type Explanation
tabid integer table identifier
turboname used on INFORMIX-OnLine only
dbname used on INFORMIX-OnLine only
tabname used on INFORMIX-OnLine only
owner used on INFORMIX-OnLine only
btabid integer tabid of base table or view

Index
Name Type Columns
synntabid unique tabid
synnbtabid dupls btabid

System Catalogs B-5

The SYSSYNTABLE Catalog

B-6 System Catalogs

Appendix

Environment
Variables
INFORMIX-4GL makes the following assumptions about
the user’s environment:
• The editor used is the predominant operating system
C
editor (usually vi).
• The database worked with is in the current directory.
• The program that sends files to the printer is lp.
• You use /tmp to store temporary files.
• The INFORMIX-4GL program and its associated files 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 environ-
ment variables recognized by INFORMIX-4GL.
You can set environment variables at the system prompt or in your .profile
(Bourne shell) or .login (C shell) file. 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 .profile (Bourne shell) or .login (C shell)
file, 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 specifies that you want to initiate Informix extension check-
ing. Setting the DBANSIWARN environment variable before you compile a
4GL program is functionally equivalent to compiling with the -ansi flag.
When Informix extensions to ANSI standard syntax are encountered in your
program, warning messages are written to a .err file. At run time, the DBAN-
SIWARN 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 sufficient. Set the DBANSIWARN envi-
ronment 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 specifies the field delimiter used by the dbload utility in
unloaded data files. The vertical bar ( | = ASCII 124) is the default.
For example, to make plus ( + ) the field delimiter on a C shell system, enter:
setenv DBDELIMITER +

DBDATE
DBDATE specifies 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 four-

digit 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
definition.

Environment Variables C-3

DBEDIT

The separator value must always be specified last. The number of digits spec-
ified for the year must always follow the Y. To make the date appear as
mmddyy (with no separator), you would set the DBDATE environment vari-
able 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=DMY4-
export DBDATE

DBEDIT
DBEDIT names the text editor for creating program files, form specification
files, and command files from within the INFORMIX-4GL Programmer’s
Environment. For most systems, the default is vi.

DBLANG
DBLANG specifies the subdirectory of $INFORMIXDIR that contains
the message (.iem) files 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, per-

form 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 files to the message directory specified by $INFORMIXDIR/

$DBLANG. All files 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 specified 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 previ-
ously specified a back symbol).

DBPATH
DBPATH specifies a list of directories (in addition to the current directory) for
INFORMIX-4GL to search for databases and associated files. 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 first 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 files.
For example, if you want INFORMIX-4GL to search for database files in
Kevin’s and Zooie’s 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 specifies the print program for your computer. For most UNIX sys-
tems, the default program is lp.

DBTEMP
DBTEMP specifies the directory into which INFORMIX-4GL should place its
temporary files. The default is the /tmp directory.

C-6 Environment Variables

INFORMIXDIR

INFORMIXDIR
INFORMIXDIR specifies the directory containing the INFORMIX-4GL files. The
default is the /usr/informix directory.

INFORMIXTERM
INFORMIXTERM specifies whether INFORMIX-4GL should use the termcap or
terminfo files 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 INFOR-
MIX-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 identifiers or as program vari-
able or host variable names. If you use reserved words as
identifiers or variables, your program (or SQL statement)
may fail with an error.
This list contains reserved words from all Informix prod-
ucts, 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
D
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 identifi-
ers.
In addition to the words on this list, you should not use C,
ADA, or COBOL language keywords in your programs.
abort char defaults extent
absolute character defer extern
accept check define external
access clear delete false
add clipped delimiter fetch
after close delimiters field
all cluster desc file
allowing col descending finish
alter color describe first
and colors descriptor fixchar
ansi column dim float
any columns dirty flush
array command display for
as comment displayonly foreach
asc comments distinct form
ascending commit do format
ascii committed dominant formonly
at composites double found
attribute compress down fraction
attributes connect downshift free
audit constant drop from
auto constraint dtime function
autonext construct dtime_t globals
average continue eco-* go
avg convert editadd go to
background count editupdate goto
before create else grant
begin current end green
beginning cursor end-exec group
bell cyan endif having
between database ending header
black date error headings
blanks datetime escape help
blink date_type every hold
blue day exclusive hour
bold dba exec identified
border debug execute if
bottom dec exists ifdef
buffered decimal exit ifndef
by decimal_type exitnow immediate
byte declare exits in
call dec_t explain include
case default extend index

D-2 Reserved Words

indicator main otherwise report
infield margin out required
info master outer resource
initialize matches output return
input max package returning
insert mdy page reverse
instructions memory pageno revoke
int menu param right
integer message pause rollback
interrupt min percent rollforward
intersect minus perform row
interval minute picture rowid
into mod pipe rows
intrvl_t mode positive run
inverse modify precision savepoint
invisible module prepare screen
is money previous scroll
isam month print second
isolation name printer section
join natural prior select
joining need privilege serial
key new privileges serial_type
label next program set
last nextfield prompt share
left no public shift
len nocr put short
length noentry query short_float
let normal queryclear short_integer
like not quit sitename
line not found raise size
lineno notfound range skip
lines noupdate read sleep
load now readonly smallfloat
locator null real smallint
lock numeric record some
loc_t of recover space
log off red spaces
long on register sql
long_float open relative sql*
long_integer option remove sqlca
lookup options rename sqlchar_type
loop or repair sqlda
magenta order repeatable sqldecimal_type

Appendix D: Reserved Words 3

sqlerr subtype typedef wait
sqlerror sum undef waiting
sqlfloat_type synonym underline warning
sqlint_type systables union weekday
sqlmoney_type table unique when
sqlsmfloat_type temp units whenever
sqlsmint_type text unload where
sqlwarning then unlock while
stability through up white
start thru update window
startlog time upshift with
static tiny_integer user without
statistics to using wordwrap
status today validate work
stdv top values wrap
step total varchar year
stop trailer variable yellow
string trailing vc_t yes
struct true verify zerofill
subtract type view

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 files.
• The dbload utility allows you to load data from other
database systems or from raw data files into INFOR-
MIX-4GL databases.
• The dbexport utility allows you to unload a database
into ASCII files.
• The dbimport utility allows you to create a database
E
from appropriate ASCII files.
• 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-defined
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 fields that are linked to database
columns in your screen forms. It can also establish ini-
tial default values for program variables and screen
fields that you associate with columns of tables in your
database.
The bcheck Utility

The bcheck Utility

For every database table, INFORMIX-4GL creates two files in the database
directory. These files have names consisting of a few characters of the table
name, a unique number (starting at 100), and a filename extension. The exten-
sion .dat identifes the data file, while the extension .idx identifies the index
file. In the stores database, for instance, data in the customer table is stored
in a file named custome100.dat, while a file named custome100.idx contains
the table indexes. To identify the actual filenames that INFORMIX-4GL has
assigned on your system, you can examine the stores.dbs directory, where
both files reside.
Should these files be damaged, you may experience symptoms ranging from
sluggish performance to seemingly missing data. The bcheck utility, sup-
plied with INFORMIX-4GL on INFORMIX-SE, can verify the integrity of both
files and repair and rebuild corrupted indexes. If you have used INFOR-
MIX-4GL only as described in your manual and have not intentionally mod-
ified these files in some other way, any damage is normally due either to
power fluctuations or to hardware problems in your mass storage system.
The bcheck utility compares an index file to a data file 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 data-
base 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
finds 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 Check index file only
-l List entries in B+ trees
-n Answer no to all questions
-y Answer yes to all questions
-q Suppress printing of the program banner
-s Resize the index file node size
The bcheck command syntax is as follows:
bcheck -[i | l | y | n | q | s] filename

Unless you use the -n or -y option, bcheck is interactive, waiting for you to
respond to each error that it finds.
Use the -y option with caution. Do not run bcheck using the -y option if you
are checking the files for the first time.

INFORMIX-4GL Utility Programs E-3

The bcheck Utility

Here is an example of bcheck output in which bcheck finds 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.

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 finds 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 data record free list

Recreate index 3
Recreate index 2
Recreate 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

Overview
Use dbexport to unload a database into ASCII files for import into another
database environment.

Syntax
dbexport [ -c ] [ -q ] database
[ -o directory-path | -t device -b blksize -s tapesize [ -f pathname ] ]

Explanation
dbexport is the program name.
-c tells the program to continue even though errors occur.
-q tells the program not to display anything on its standard
output.
database is the name of the database to be exported.
-o directory-path directs the output to a specified directory on disk.
-t device directs the output to a specified tape device.
-b blksize specifies the tape block size in kilobytes.
-s tapesize specifies the capacity of one tape reel.
-f pathname tells the program to write data definition statements to the
file pathname and not to the tape.

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 file of messages called
dbexport.out. This file contains any error messages and warnings, and it
also contains a display of the SQL data definition statements that it is gen-
erating. 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 pro-
gram asks for confirmation before terminating.
5. The dbexport program writes multiple files containing database data,
either to disk or to tape. The -t option specifies that the destination is a
tape drive; otherwise, dbexport writes the files 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 file of data definition statements and
other commands (used by the dbimport utility) are ordinarily also writ-
ten to the tape. Use the -f option to instruct the program to write these to
the file 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 directory-
path option, the database.exp directory is located in the specified directory.
By default, the database is placed in your current working directory.
8. When output is to disk, the file containing the data definition statements
and other commands to dbimport is written to the file 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 file of data defini-
tion 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 INFORMIX-
OnLine Programmer’s Manual for more information.

INFORMIX-4GL Utility Programs E-7

The dbimport Utility

Overview
Use dbimport to create a database from ASCII files.

Syntax
dbimport [-c] [-q] database
[-i directory-path |-t device -b blksize -s tapesize [-f pathname] ]
[-d dbspace] [-l [ logpath | buffered] ] [-ansi]

Explanation
-c tells the program to continue even when errors occur, unless
it is a fatal error.
-q tells the program not to display anything on its standard
output.
database is the name of the database to import.
-i directory-path specifies the path to an input directory.
-t device specifies input from a particular tape device.
-b blksize specifies the tape block size in Kbytes.
-s tapesize specifies the capacity of one tape reel.
-f pathname tells the program to read data definition statements from the
file pathname and not from the tape.
-d dbspace when importing to INFORMIX-OnLine only, specifies the
dbspace where the new database is to go.
-l specifies that the imported database is to use transaction
logging.
logpath when importing to the standard database engine only, spec-
ifies the pathname of the transaction log file.
buffered when importing to INFORMIX-OnLine only, specifies buff-
ered or unbuffered logging (unbuffered is the default).
-ansi tells the program to create the new database as MODE ANSI.

E-8 INFORMIX-4GL Utility Programs

The dbimport Utility

Notes
1. The program always creates a message file called dbimport.out in the
current directory. This file contains messages and warnings related to the
running of the program. The message are also written to the standard out-
put (normally the terminal screen) unless you include the -q option.
2. You can cancel the program with an interrupt signal. You are prompted
for confirmation 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, data-
base files are created in the current directory.
5. Use the -l option to establish transaction logging for the imported data-
base. This option is equivalent to the WITH LOG IN clause of the CREATE
DATABASE statement. A database created as MODE ANSI requires trans-
action logging. In this situation, you must include the -l option.
6. The dbimport utility reads multiple files 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 definition
statements and other dbimport commands from the tape. Use the
-f pathname option to instruct the program to read the database.sql file in
pathname (instead of the tape) for the data definition 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 specified
with the -i option. In either case, the program takes data definition and
other commands from the file 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 file of data defini-
tion 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 definition and commands from the file
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 INFORMIX-

OnLine Programmer’s Manual for more information.

E-10 INFORMIX-4GL Utility Programs

The dbload Utility

The dbload utility provides a method for transferring data from ASCII files
into an existing database. This program supports the easy and efficient trans-
fer of database files created for other Informix products, or even for entirely
different database management systems. The dbload utility includes the fol-
lowing features:
• Data from selected fields of one or more input files can be loaded into
selected columns of one or more database tables.
• Loading can begin at any line in the input file.
• Loading proceeds in batches of n records (where n is an integer that you
specify).
• Both fixed- and variable-length data records can be loaded.
• NULL values can be defined for any field 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 file.
• 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 terminat-
ing 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 file of data records to
enter, and at least one table to receive the data. You must then create a
command file to specify instructions for reading and loading the data. Finally,
you must invoke dbload by entering an appropriate command line. The fol-
lowing sections provide details about these procedures.

Input Files for the dbload Utility

Just as database tables store data in columns within rows, input file data must
be arranged in fields within records. You must be able to specify a one-to-one
correspondence between fields of the input records and columns of the new
rows that dbload will insert in the database.
Data files for dbload must be ‘‘flat’’ ASCII files, containing only printable
characters. The records containing the data to be transferred must be sepa-
rated by the NEWLINE character. Output from the UNLOAD statement of SQL,
for example, can be used as an input file by dbload.

INFORMIX-4GL Utility Programs E-11

The dbload Utility

Fixed-Length and Variable-Length Records

The record length can be either fixed or variable. An input file has fixed-length
records if the locations of data fields and the number of characters are the
same across all records. If a file has variable-length records, every field must
end with the same delimiter character (which must not occur as data within
any field). This character does not need to be the same one that the DBDELIM-
ITER environment variable specifies.

Two consecutive delimiters in a variable-length record define a NULL field.

For each field in a fixed-length record, you can use the dbload command file
to specify a character string to store as a NULL value.

Data Type Formats

Leading blanks are allowed in data fields. A currency symbol is optional in
data fields 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 field digits
and delimiters (no type or qualifiers):
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 first create an ASCII command file that
maps fields from one or more input files into columns of one or more tables
within your database. This command file must specify two kinds of
information:
• One or more FILE statements, to define data fields within the records of
the input file(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 files 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 defining 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 file for dbload is indicated here:

FILE { "filename" }

{ DELIMITER "c" nfields |

(fieldn1 start [ - end ] [: . . . ] [ NULL = "null-str1" ] ,

fieldn2 start [ - end ] [: . . . ] [ NULL = "null-str2" ] ,
. . .
fieldnN start [ - end ] [: . . . ] [ NULL = "null-strN" ] ) } ;

INSERT INTO tablename [ (column-list) ] [ VALUES (value-list) ] ;

[ . . . ]
The command file can include multiple FILE and INSERT statements. An
explanation of these terms, notes, and an example follow.

Explanation
FILE is a required keyword.
filename is the pathname of an input file, enclosed between a pair of
quotation ( " ) marks.
DELIMITER is a keyword that is required if filename has variable-length
data records.
c is the field delimiter (enclosed in quotes) between fields of a
variable-length data record, and before the NEWLINE char-
acter that terminates each record.
nfields is an integer, specifying the number of fields in each vari-
able-length data record.
fieldn is a name that you assign to a data field within a fixed-length
record of filename.
start is an integer, indicating a character position within a fixed-
length record.
-end is a hyphen ( - ) and an integer, indicating (with start) a range
of character positions.
NULL is a keyword to specify a NULL symbol.
null-str is a quoted string, specifying a data value for which dbload
should substitute a NULL.
INSERT INTO are required keywords.
tablename identifies a table in which to store the data.

INFORMIX-4GL Utility Programs E-13

The dbload Utility

column-list is a list of column names within tablename, separated by

commas.
VALUES is an optional keyword to specify a list that can include con-
stants and data field names.
value-list is a comma-separated list of constants and/or data field
names from filename.

Notes
1. The dbload utility recognizes valid owner.table references.
2. You need UNIX read permission for filename, 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
defined with the DELIMITER option.
5. Use a colon ( : ) to separate character position or range values in each data
field definition. The list of field definitions must be enclosed in parenthe-
ses and separated by commas.
6. The same character position can be repeated in the FILE specification of a
field, or in different fields. (See the command file example that follows
these notes.)
7. The scope of reference of a null-str is the field for which you define it, but
you can define the same null-str for other fields.
8. The DELIMITER option automatically assigns the sequential names f01,
f02, f03, . . . to fields in variable-length records. The value-list of an INSERT
statement can reference field 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 field 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 restric-
tion 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 field 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 trun-
cated if the field is wider.
13. Enclose between braces ( { } ) any comments in filename.
14. Use the DELIMITER option to avoid truncation of long character fields. If
the delimiter c (or a backslash) appears as a literal character, you must
prefix it with a backslash ( \ ) in the input file.
15. If you specify DELIMITER, the same delimiter must be used throughout
the input file and must appear in quotes in the FILE statement. You must
remember to place the delimiter immediately before the NEWLINE char-
acter that marks the end of each record. (If you omit this delimiter, an
error results whenever the last field 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}

FILE "datafile.2" DELIMITER "|" 8 ; {variable-length fields}

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 files. Unless you use the DELIMITER option, for example, you
must explicitly list every field that a FILE statement defines. Each statement in this
example is described in the pages that follow.
FILE "datafile1" (fld1 1 - 10 : 13 : 5 - 22 NULL = "str1" ,

Here datafile1 is the input file, and fld1, fld2, fld3, through fldN are user-
assigned field names in its fixed-length data records. In this example, fld1
consists of the characters in positions 1 through 10, 13, and 5 through 22 of
every datafile1 record. (Each record ends with a NEWLINE character.) Notice
that the characters 5 through 10 and 13 appear twice in fld1, and characters
10, 13, and 21 appear in fld1 and fld2.
In field fld1, the NULL symbol is defined as ‘‘str1.’’ A NULL value is entered
whenever ‘‘str1’’ is read in fld1.

INFORMIX-4GL Utility Programs E-15

The dbload Utility

The fld2 field consists of positions 10 through 21, and 28 through 32.
The fld3 field is defined as the characters in positions 8 through 10, 33 through
50, and 29 through 33. The NULL symbol for field fld3 is defined as ‘‘str2.’’
The field-definition process continues until the last field is reached. Field fldN
contains characters in positions 9, and 16 through 19. The NULL value is
defined 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 fields defined in the preceding FILE statement. It
inserts the data from fld1 into col1, from fld2 into col2, from fld3 into col9, and
so forth, until the value from fldN 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 speci-
fied by field names from the previous FILE statement or as constants. Data in
fld1 go into the first column, data from fld3 into the second, and the constant
‘‘kevin’’ into the third. The dbload utility continues until the value in fldN is
inserted into the final column.
INSERT INTO tab3 ; {no column or values list provided}

As noted in the comment, this statement specifies 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 first statement in the command file. Data from fld1 go into the first col-
umn, data from fld2 into the second, and so forth, with data from field fldN
going into the Nth column.
Note: This statement requires that the field list in the FILE statement have a one-to-
one 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 file datafile.2 has variable-length
fields, and that the vertical-bar character ( | = ASCII 124) separates each field.
Here 8 is the number of fields 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 specified, so dbload reads all the column

names of tab1 from the system catalogs. Here the value in field f01 goes into
the first 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 field
f08 is inserted into the last column.
You must reference fields in a variable-length data file with the letter f fol-
lowed 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 finds all the names of col-
umns in table tab4 in the system catalogs. The value-list is all the fields
defined 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 field f01 goes into the first 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 file, you invoke dbload at the oper-
ating 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 dis-
plays a syntax summary for dbload usage, and control returns to the operat-
ing system.

INFORMIX-4GL Utility Programs E-17

The dbload Utility

To use dbload to read and execute a command file, you must enter a com-
mand line that includes at least one of its required specifications. The follow-
ing elements are required in a dbload command line:
dbload { -d database | -c comfile | -l logfile } . . .
dbload invokes the dbload utility.
-d database identifies a database to receive the new data.
-c comfile identifies a dbload command file.
-l logfile identifies a file 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 specifications. Depending on what you entered at the com-
mand line, these specifications can include
• The name of the database to receive the new data.
• The name of the command file to be executed.
• The name of an error log file in which to store any input file 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 file, without changing the database.
• How many bad input records can be encountered before dbload stops
inserting new rows.
• How many input file 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 suc-
cessfully read between the last COMMIT and the first 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 specifications or press RETURN to accept the default
values that appear in the prompts, the screen is cleared, and the dbload util-
ity 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 file,
and error log specifications, with or without any additional options, program
execution begins. The complete syntax of dbload is indicated here:

Syntax
dbload -d database -c comfile -l logfile
[ -e num1 ] [ -n num2 ] [ -i num3 ] [ -p ] [ -r ] [ -s [ > outfile ] ]

Explanation
dbload is a required keyword.
-d database is the name of a database to receive the data.
-c comfile is the pathname of a dbload command file.
-l logfile is the pathname of an error logging file.
-e num1 is the number of bad records that dbload will read before it
terminates (where num1 is an integer).
-n num2 displays a message after each batch of num2 new rows are
inserted (where num2 is an integer).
-i num3 ignores the first num3 input records (where num3 is an
integer).
-p prompts for instructions if the number of bad records
exceeds num1.
-r instructs dbload not to lock the table(s). (Otherwise, table-
level locking occurs during loading.)
-s instructs dbload only to check the syntax of the statements
in comfile, without inserting any data.
> outfile is an optional > symbol and the name of a file in which to
save output from the syntax check.

Notes
1. Unless you include at least one of the first 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 specifications.
2. You can prefix comfile, logfile, or outfile with a pathname.

INFORMIX-4GL Utility Programs E-19

The dbload Utility

3. You should run dbload with the -s or -s > outfile options before you begin
loading data. These options perform a syntax check on the FILE and
INSERT statements in comfile and ignore any other options except -d data-
base and -c comfile. The screen displays comfile 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 first 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 first num3 lines in the input
file, 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 file ended after 240 lines of input. You
can resume loading at line 241 by setting num3 equal to 240. It is also use-
ful if header information in the input file 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 finished.

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 specifies the following parameters:
-d stores is the name of the database to receive the data.
-c cfyl is the name of the dbload command file.
-l lfyl is the name of the error-log file.

E-20 INFORMIX-4GL Utility Programs

The dbload Utility

-e 5 specifies that dbload will log up to five bad records. The pro-
gram terminates if a 6th bad record is encountered.
-n 75 specifies that screen messages will indicate when successive
batches of 75 rows have been inserted (or committed, in a
database with transactions).
-i 20 tells dbload to ignore the first 20 lines of the data file. Pro-
cessing begins at the 21st line.
-p prompts you to commit or discard any uncommitted rows
after six bad records.
-r 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.
Notice that the names of the input file and the table(s) to receive the data do
not appear explicitly in the command line. These names must be specified
within the dbload command file, which is called cfyl in this example.

INFORMIX-4GL Utility Programs E-21

The dbschema Utility

You can use the dbschema utility to produce quickly an SQL command file
containing the CREATE TABLE, CREATE INDEX, and CREATE VIEW state-
ments 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 state-
ments, 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 out-
put before running it as an SQL script.
The syntax for the dbschema utility follows:
dbschema [-t tabname] [-s sname] [-p pname] -d database [filename]
-t tabname specifies 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.
-s sname specifies 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.
-p pname specifies the user for whom you want dbschema to output per-
mission 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.
-d database specifies the name of the database.

E-22 INFORMIX-4GL Utility Programs

The dbschema Utility

filename specifies the name of the file in which to save the dbschema
output. If filename 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 filter
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 first change the owner names in the output file.
5. All SERIAL fields included in CREATE TABLE statements output by
dbschema have a starting value of one, regardless of their original start-
ing 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 file 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 file 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

Databases created through Informix products that used an early implemen-
tation 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 exist-
ing 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 con-
vert 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 define all columns as NOT
NULL, and does not touch the data files. 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 finishes, you have two database directories (the new and the
old) with two separate system catalogs, but the data and index files 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, define all columns as NOT NULL.
• In all form specification files, add the WITHOUT NULL INPUT clause in the
DATABASE section.
• In form specification files, specify all formonly fields as NOT NULL.
The last two rules mean that you must recompile all your old form specifica-
tion files.

E-26 INFORMIX-4GL Utility Programs

The mkmessage Utility

The mkmessage utility converts ASCII source files 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 files and with customized run-
time error messages.

Programmer-Defined 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 (specified in the OPTIONS statement). These messages
can be specific 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 file that
you specify in an OPTIONS statement, using the HELP FILE option. You can
have several help files, but only one can be in effect at a time. The structure
of the message source file is very simple:

Syntax
.num
message-text
...
[ ... ]

Explanation
.num is a period, followed by an integer.
message-text 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 first 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 num-
bered line.
4. You can use the integer num to identify the help message in your INFOR-
MIX-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 first 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 auto-
matically breaks the message into ‘‘pages’’ of 20 lines. You can change
these default page breaks by entering CTRL-L in the first column of a line
in your message file to start a new page.
8. INFORMIX-4GL handles clearing and redisplaying the screen.

Examples
For an example, see the helpdemo.src file from the demonstration applica-
tion 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 file, you can process it for use by
INFORMIX-4GL with this syntax:

Syntax
mkmessage helpfile.src helpfile.out

Explanation
helpfile.src is an ASCII source file of help messages.
helpfile.out is the pathname of the executable output file.

E-28 INFORMIX-4GL Utility Programs

The mkmessage Utility

Notes
1. You can give the input and output help files any valid names and exten-
sions in place of those shown above.
2. You can specify the output help file name in the OPTIONS statement to
identify it as the current help file.
3. If you want to use help messages from the help file on a field-by-field
basis in an INPUT or INPUT ARRAY statement, you must use the infield()
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 mes-
sages. INFORMIX-4GL is distributed with a file called 4glusr.msg. This ASCII
file 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 file contains the executable version of this file.
You can edit the messages in 4glusr.msg with a text editor (for example, to
make them specific to a 4GL application, or to translate them into another lan-
guage). Be sure to preserve the required numeric codes, prefixed 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 file, you must
specify 4glusr.iem in your mkmessage command line as the object file name:
mkmessage source-file-name 4glusr.iem
The executable file 4glusr.iem is initially installed in the directory $INFOR-
MIX/msg. INFORMIX-4GL looks for message files in one of two directories,
namely /$INFORMIXDIR/$DBLANG or else
/$INFORMIXDIR/msg. If $DBLANG is defined, 4GL looks only in
/$INFORMIXDIR/$DBLANG. If this is not defined, 4GL looks only in
/$INFORMIXDIR/msg. You must place the newly modified file 4glusr.iem
in the appropriate /$INFORMIXDIR/msg or /$INFORMIXDIR/$DBLANG
directory.

E-30 INFORMIX-4GL Utility Programs

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 SQL-
compatible database. It leaves the old database intact.
This appendix discusses the steps necessary to convert an INFORMIX data-
base 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 con-
straints of your system.
Caution: sqlconv will not convert INFORMIX database permissions. You must
grant new permissions on tables and fields after your new 4GL database has been cre-
ated 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 field 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 fields are indexed. Indexed composite fields 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 files
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 files. 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 INFOR-
MIX-4GL directory.
3. Change your current directory to the directory that contains your INFOR-
MIX 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 filename extension. This command generates
an INFORMER script file (indicated by a .uld extension), an INFOR-
MIX-4GL program (indicated by a .4gl extension), and a dbload com-
mand file (indicated by a .cmd extension).
6. Enter
informer databasename databasename.uld

This command unloads the database files (in ASCII format) to unload files
(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 file with extension .out.
If you have the RDS version of INFORMIX-4GL, enter
fglpc databasename.4gl

This creates a p-code file 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 file 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 files (generated by informer)
into the appropriate tables, and creates an errlog file, which contains diag-
nostic information about any rows that were not successfully loaded. For
more information on dbload, see “The dbload Utility” in this appendix.
10. The final step in the conversion procedure is to remove all the old data-
base files, and the .uld, .4gl, .cmd, .unl, .out or .4go files from your
directory, and any .ec or .c files 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 data-
base, 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 INFOR-
MIX-4GL directory.
3. Change your current directory to the directory that contains your INFOR-
MIX database.
4. Create a backup copy of the INFORMIX database.
5. Enter
sqlconv -e payroll

Do not include a filename extension. This command generates an

INFORMER script file (indicated by a .uld extension), an 4GL program
(indicated by a .4gl extension), and a dbload command file (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 file.
If you have the RDS version of INFORMIX-4GL, enter
fglpc payroll.4gl

This creates a p-code file payroll.4go from the 4GL program that you cre-
ated 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 file 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 file outline the first steps of the conver-
sion operation. You must execute each of these statements separately. You
may find it helpful to print a copy of the payroll.uld file for easy refer-
ence.
9. Enter
informer payroll

At the INFORMER prompt, enter the first line of the payroll.uld file
exactly as it appears. This creates the unload file for the first table. Exit
from INFORMER.
10. The .cmd file describes the form of the data and contains the INSERT INTO
statements indicating how this data is to be placed in the database files.
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 file for each INSERT INTO state-
ment and make sure you include the .cmd extension to the filename of
each new file. In this instance, we have named the files one.cmd and
two.cmd.
11. Edit the one.cmd file using your system editor, and remove all but the
first INSERT INTO statement from the file. Exit from the file.
12. Execute the first INSERT INTO statement in the one.cmd file by entering
dbload -d payroll -c one.cmd -l errlog

This command loads the data from the .unl file into the appropriate table
and creates an errlog file, 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 file. 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 files. To erase these files, enter
dbstatus payroll

14. At the dbstatus prompt, enter

erase file filename

where filename is the name of the file referred to in the .cmd file created in
Step 11. Exit from dbstatus.

INFORMIX-4GL Utility Programs E-35

The sqlconv Utility

15. Erase the unload file for this same file by entering from the command line
rm filename.unl

16. Continue to unload each table, one at a time, from the INFORMIX data-
base 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 file
for each INSERT INTO statement it contains. Each copy must have a
unique name and must end in the .cmd extension. The correct filename
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 file have
been executed. This operation loads the actual data into the newly created
database.
17. Check the contents of the data files 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 files from your directory (and any .ce or .c files that
may have been created if you have the C Compiler Version of INFOR-
MIX-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 con-
vert the table.

E-36 INFORMIX-4GL Utility Programs

The upscol Utility

The upscol utility program allows you to create and modify the syscolval
and syscolatt tables, which contain default information for fields 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 Update the information in syscolval.
Attributes Update the information in syscolatt.
Exit Return to the operating system.
If you select either Validate or Attributes, upscol checks whether the corre-
sponding 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 first row of syscol that relates to tab-name and
col-name in the work area beneath this menu. If no such entries exist, a mes-
sage stating this appears on the Error line.
The options in the ACTION Menu are
Add Add new rows to the syscol table.
Update Update the currently displayed row.
Remove Remove the currently displayed row (after a prompt for
verification).
Next Display the next row of syscol.
Query Restart the display at the first row of syscol for tab-name and
col-name.
Table Select a new database table and column.
Column Select a new column within tab-name.
Exit 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 Exit

Automatically proceed to next field when at end of current field.

--------- db-name:tab-name:col-name ------------ Press CTRL-W for Help --------

The options are attribute names and their selection has the following effects:
Autonext Produces a menu with three options, Yes, No, and Exit. Exit
returns you to the VALIDATE Menu. The default is No.
Comment Produces a prompt to enter a Comment line message. No
quotation marks are required around the comment, but it
must fit on a single screen line.
Default Produces a prompt to enter the DEFAULT attribute, format-
ted as described in Chapter 4. Quotation marks are required
where necessary to avoid ambiguity.
Include Produces a prompt to enter the INCLUDE attribute, format-
ted as described in Chapter 4. Quotation marks are required
where necessary to avoid ambiguity.
Picture Produces a prompt to enter the PICTURE attribute, formatted
as described in Chapter 4. No quotation marks are required.
Shift 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.
Verify Produces a menu with three options, Yes, No, and Exit. Exit
returns you to the VALIDATE Menu. The default is No.
Exit Returns you to the ACTION Menu.
The upscol utility adds or modifies 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 col-
umn 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 Left Rev Under Where Discrd_Exit Exit_Set
Set Field blinking attribute

--------- 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 Produces a menu with three options, Yes, No, and Exit. The
default is No.
Color Produces a menu with the available colors (color terminals)
or intensities (monochrome terminals) for display of tab-
name.col-name. The colors displayed are those in the local
colornames file, whose format is described in Appendix I. If
no such file exists locally, upscol looks in $INFORMIXDIR/
incl. If the file 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 Prompts you for the format string to be used when tab-
name.col-name is displayed.
Left Produces a menu with three options, Yes, No, and Exit. Yes
causes numeric data to be left justified within the screen
field. The default is No.
Rev Produces a menu with three options, Yes, No, and Exit. Yes
causes the field to be displayed in reverse video. The default
is No.
Under Produces a menu with three options, Yes, No, and Exit. Yes
causes the field to be displayed with underlining. The
default is No.
Where Prompts for the values and value ranges under which these
attributes will apply. See Chapter 4 for allowable syntax.
Discrd_Exit Discards the indicated changes and returns to the ACTION
Menu.
Exit_Set Enters the indicated changes into the syscolatt table and
returns to the ACTION Menu.
After you complete each of these options except Discrd_Exit, upscol adds or
modifies 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 specified at the upscol menus, but
other users can produce their own user. syscolval and user.syscolatt tables. The
default specifications in an upscol table are applied by INFORMIX-4GL only to col-
umns 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 signif-
icant 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 man-
tissa (or fractional part) in base 100. In normalized form, the
first digit of the mantissa must be greater than zero.

F
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 file decimal.h. Include this file
in all C source files that use any of the decimal routines:
#include <decimal.h>
DECIMAL-Type Routines

The decimal structure has four parts:

dec_exp holds the exponent of the normalized DECIMAL-type num-
ber. This exponent represents a power of 100.
dec_pos holds the sign of the DECIMAL-type number (1 when the
number is zero or greater; 0 when less than zero).
dec_ndgts contains the number of base 100 significant digits of the
DECIMAL-type number.
dec_dgts is a character array that holds the significant 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 significant 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 follow-
ing pages. Any other operations, modifications, 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( ) convert C char type to DECIMAL-type
dectoasc( ) convert DECIMAL-type to C char type
deccvint( ) convert C int type to DECIMAL-type
dectoint( ) convert DECIMAL-type to C int type
deccvlong( ) convert C long type to DECIMAL-type
dectolong( ) convert DECIMAL-type to C long type
deccvflt( ) convert C float type to DECIMAL-type
dectoflt( ) convert DECIMAL-type to C float type
deccvdbl( ) convert C double type to DECIMAL-type
dectodbl( ) convert DECIMAL-type to C double type
decadd( ) add two decimal numbers
decsub( ) subtract two decimal numbers
decmul( ) multiply two decimal numbers
decdiv( ) divide two decimal numbers
deccmp( ) compare two decimal numbers
deccopy( ) copy a decimal number
dececvt( ) convert decimal value to ASCII string
(corresponds to ecvt(3) on UNIX systems)
decfcvt( ) convert decimal value to ASCII string
(corresponds to fcvt(3) on UNIX systems)

F-2 DECIMAL Functions for C

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 points to a string that holds the value to be converted.
len is the length of the string.
np 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 deci-
mal 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 Function was successful.
-1200 Number is too large to fit into a DECIMAL-type (overflow).
-1201 Number is too small to fit into a DECIMAL-type (underflow).
-1213 String has non-numeric characters.
-1216 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

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 is a pointer to the decimal structure whose associated decimal value
you want to convert to an ASCII string.
cp is a pointer to the beginning of the character buffer to hold the ASCII
string.
len is the maximum length in bytes of the string buffer.
right 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 dec-
imal value of *np.
2. If the number does not fit into a character string of length len, dectoasc
converts the number to exponential notation. If the number still does not
fit, dectoasc fills the string with asterisks. If the number is shorter than the
string, it is left-justified 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 Conversion was successful.
-1 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

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

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 is a pointer to a decimal structure whose value is converted to an
integer.
ip is a pointer to the integer.

Return Codes
0 Conversion was successful.
-1200 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

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 is a pointer to a long integer.
np 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

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 is a pointer to a decimal structure.
lngp is a pointer to a long where the result of the conversion will be
placed.

Return Codes
0 Conversion was successful.
-1200 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

Overview
Use deccvflt to convert a C type float into a DECIMAL-type number.

Syntax
deccvflt(flt, np)
float flt;
dec_t *np;

Explanation
flt is a floating-point number.
np 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

Overview
Use dectoflt to convert a DECIMAL-type number into a C type float.

Syntax
dectoflt(np, fltp)
dec_t *np;
float *fltp;

Explanation
np is a pointer to a decimal structure.
fltp is a pointer to a floating-point number to receive the result of the
conversion.

Notes
The resulting floating-point number has eight significant 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

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 is a double-precision, floating-point number.
np 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

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 is a pointer to a decimal structure.
dblp is a pointer to a double-precision, floating-point number that
receives the result of the conversion.

Notes
The resulting double-precision number receives a total of 16 significant
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

Overview
The decimal arithmetic routines take pointers to three decimal structures as
parameters. The first two decimal structures hold the operands of the arith-
metic function. The third decimal structure holds the result.

Syntax
decadd(n1, n2, result) /* result = n1 + n2 */
dec_t *n1;
dec_t *n2;
dec_t *result;

decsub(n1, n2, result) /* result = n1 - n2 */

dec_t *n1;
dec_t *n2;
dec_t *result;

decmul(n1, n2, result) /* result = n1 * n2 */

dec_t *n1;
dec_t *n2;
dec_t *result;

decdiv(n1, n2, result) /* result = n1 / n2 */

dec_t *n1;
dec_t *n2;
dec_t *result;

Explanation
n1 is a pointer to the decimal structure of the first operand.
n2 is a pointer to the decimal structure of the second operand.
result 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 Operation was successful.
-1200 Operation resulted in overflow.
-1201 Operation resulted in underflow.
-1202 Operation attempts to divide by zero.

F-16 DECIMAL Functions for C

DECCMP

Overview
Use deccmp to compare two DECIMAL-type numbers.

Syntax
int deccmp(n1, n2)
dec_t *n1;
dec_t *n2;

Explanation
n1 is a pointer to the decimal structure of the first number.
n2 is a pointer to the decimal structure of the second number.

Return Codes
0 The two values are the same.
-1 The first value is less than the second.
+1 The first value is greater than the second.

DECIMAL Functions for C F-17

DECCOPY

Overview
Use deccopy to copy one dec_t structure to another.

Syntax
deccopy(n1, n2)
dec_t *n1;
dec_t *n2;

Explanation
n1 is a pointer to the source dec_t structure.
n2 is a pointer to the destination dec_t structure.

F-18 DECIMAL Functions for C

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 is a pointer to a dec_t structure that contains the number you want to
convert.
ndigit is, for dececvt, the length of the ASCII string; for decfcvt, it is the
number of digits to the right of the decimal point.
decpt 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.
sign 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.

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 specifies the
number of digits to the right of the decimal point instead of the total num-
ber 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 = dececvt (np,4,&decpt,&sign); = 1235
ptr = dececvt (np,10,&decpt,&sign); = 1234567000
ptr = decfcvt (np,1,&decpt,&sign); = 123457
ptr = decfcvt (np,3,&decpt,&sign); = 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 = dececvt (np,4,&decpt,&sign); = 1234
ptr = dececvt (np,10,&decpt,&sign); = 1234000000
ptr = decfcvt (np,1,&decpt,&sign); =
ptr = decfcvt (np,3,&decpt,&sign); = 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 first glance, both fetch the same data.
The query results, however, are quite different, as the fol-
lowing illustration shows.

G
How Outer Joins Work

customer_num lname order_num customer_num lname order_num

104 Higgins 1001 101 Pauli 1002

101 Pauli 1002 102 Sadler
104 Higgins 1003 103 Currie
106 Watson 1004 104 Higgins 1001
116 Parmelee 1005 104 Higgins 1003
112 Lawson 1006 104 Higgins 1011
117 Sipes 1007 104 Higgins 1013
110 Jaeger 1008 105 Vector
111 Keyes 1009 106 Watson 1004
115 Grant 1010 106 Watson 1014
104 Higgins 1011 107 Ream
117 Sipes 1012 108 Quinn
104 Higgins 1013 109 Miller
106 Watson 1014 110 Jaeger 1008
110 Jaeger 1015 110 Jaeger 1015
111 Keyes 1009
112 Lawson 1006
113 Beatty
114 Albertson
115 Grant 1010
116 Parmelee 1005
117 Sipes 1007
117 Sipes 1012
118 Baxter
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 cre-
ates 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 combina-
tions 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 depts

emp_num dept_num dept_num dept_loc

2 105 102 NY
4 103 103 LA
6 103 105 SF
5 —
3 102
Suppose, for example, that you need a list of employee numbers and depart-
ment locations for all employees, including those employees whose depart-
ment 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 filters to the subservient table while sequentially applying
the join condition to the rows of the dominant table. Rows in the domi-
nant 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 sub-
servient-table row.
The result is a ‘‘table’’ with the following rows:
emp_num dept_num dept_num dept_loc
2 105 105 SF
3 102 102 NY
4 103 103 LA
5 — — —
6 103 103 LA
Note: A filter is a condition expressed in a WHERE clause that applies to col-
umns in a single table. For example,
"dept_loc = SF" or "emp_num < 105"

Because 4GL applies such filters to the subservient table as it performs the join,
the resulting ‘‘table’’ may contain NULL values that were not present in the sub-
servient table prior to the join.

Outer Joins G-3

How Outer Joins Work

Suppose that the query includes a filter 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 dept_num dept_num dept_loc
2 105 105 SF
3 102 102 NY
4 — — —
5 — — —
6 — — —
The filter removes rows from the depts table where dept_loc is equal to LA.
2. After performing the join, 4GL applies filters 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 dept_loc
2 SF
3 NY
4 LA
5 —
6 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 cor-

responding row from the customer table. Because the query does not contain
filters, 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
Figure G-4 Query 3

customer_num company order_num ship_date

101 All Sports Supplies 1002 06/06/1984

102 Sports Spot
103 Phil’s Sports
104 Play Ball! 1001 06/05/1984
104 Play Ball! 1003 06/07/1984
104 Play Ball! 1011 06/07/1984
104 Play Ball! 1013 06/11/1984
105 Los Altos Sports
106 Watson & Son 1004
106 Watson & Son 1014 06/09/1984
107 Athletic Supplies
108 Quinn’s Sports
109 Sport Stuff
110 AA Athletics 1008 06/27/1984
110 AA Athletics 1015 06/11/1984
111 Sports Center 1009 06/15/1984
112 Runners & Others 1006
113 Sportstown
114 Sporting Place
115 Gold Medal Sports 1010 06/07/1984
116 Olympic City 1005 06/08/1984
117 Kids Korner 1007 06/08/1984
117 Kids Korner 1012 06/09/1984
118 Blue Ribbon Sports
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 pos-
sible 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"
Figure G-6 Query 4

G-6 Outer Joins

Examples

4GL performs the simple join between orders and items first, yielding infor-
mation 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 order_num stock_num manu_code quantity

101 Pauli
102 Sadler
103 Currie
104 Higgins 1003 9 ANZ 1
104 Higgins 1003 8 ANZ 1
104 Higgins 1003 5 ANZ 5
104 Higgins 1011 5 ANZ 5
104 Higgins 1013 5 ANZ 1
104 Higgins 1013 6 ANZ 1
104 Higgins 1013 9 ANZ 2
105 Vector
106 Watson
107 Ream
108 Quinn
109 Miller
110 Jaeger 1008 8 ANZ 1
110 Jaeger 1008 9 ANZ 5
111 Keyes
112 Lawson 1006 5 ANZ 5
112 Lawson 1006 6 ANZ 1
113 Beatty
114 Albertson
115 Grant 1010 6 ANZ 1
116 Parmelee 1005 5 ANZ 10
116 Parmelee 1005 6 ANZ 1
117 Sipes 1012 8 ANZ 1
117 Sipes 1012 9 ANZ 10
118 Baxter
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 order_num stock_num manu_code quantity

101 Pauli 1002

102 Sadler
103 Currie
104 Higgins 1001
104 Higgins 1003 9 ANZ 1
104 Higgins 1003 8 ANZ 1
104 Higgins 1003 5 ANZ 5
104 Higgins 1011 5 ANZ 5
104 Higgins 1013 5 ANZ 1
104 Higgins 1013 6 ANZ 1
104 Higgins 1013 9 ANZ 2
105 Vector
106 Watson 1004
106 Watson 1014
107 Ream
108 Quinn
109 Miller
110 Jaeger 1008 8 ANZ 1
110 Jaeger 1008 9 ANZ 5
110 Jaeger 1015
111 Keyes 1009
112 Lawson 1006 5 ANZ 5
112 Lawson 1006 6 ANZ 1
113 Beatty
114 Albertson
115 Grant 1010 6 ANZ 1
116 Parmelee 1005 5 ANZ 10
116 Parmelee 1005 6 ANZ 1
117 Sipes 1007
117 Sipes 1012 8 ANZ 1
117 Sipes 1012 9 ANZ 10
118 Baxter
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 notes
104 sponsors soccer team
108 customer for 20 years
115 opening a second store
118 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 cus-
tomers who also have orders.
customer_num order_num notes

101 1002
102
103
104 1001 sponsors soccer team
104 1003 sponsors soccer team
104 1011 sponsors soccer team
104 1013 sponsors soccer team
105
106 1004
106 1014
107
108
109
110 1008
110 1015
111 1009
112 1006
113
114
115 1010 opening a second store
116 1005
117 1007
117 1012
118
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 order_num notes

101 1002
102
103
104 1001 sponsors soccer team
104 1003 sponsors soccer team
104 1011 sponsors soccer team
104 1013 sponsors soccer team
105
106 1004
106 1014
107
108 customer for 20 years
109
110 1008
110 1015 opening a second store
111 1009
112 1006
113
114
115 1010
116 1005
117 1007
117 1012
118 new customer
Figure G-10 Query 7 Results

All of the preceding queries fetch information from one table with supple-
mental information from other tables. When you need similar results, Infor-
mix 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 influence 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

H
Num Char Num Char Num Char
0 ^@ 43 + 86 V
1 Â 44 , 87 W
2 ^B 45 - 88 X
3 ^C 46 . 89 Y
4 ^D 47 / 90 Z
5 Ê 48 0 91 [
6 ^F 49 1 92 \
7 ^G 50 2 93 ]
8 ^H 51 3 94 ^
9 Î 52 4 95 _
10 ^J 53 5 96 `
11 ^K 54 6 97 a
12 ^L 55 7 98 b
13 ^M 56 8 99 c
14 ^N 57 9 100 d
15 Ô 58 : 101 e
16 ^P 59 ; 102 f
17 ^Q 60 < 103 g
18 ^R 61 = 104 h
19 ^S 62 > 105 i
20 ^T 63 ? 106 j
21 Û 64 @ 107 k
22 ^V 65 A 108 l
23 ^W 66 B 109 m
24 ^X 67 C 110 n
25 ^Y 68 D 111 o
26 ^Z 69 E 112 p
27 esc 70 F 113 q
28 ^\ 71 G 114 r
29 ^] 72 H 115 s
30 ^^ 73 I 116 t
31 ^_ 74 J 117 u
32 75 K 118 v
33 ! 76 L 119 w
34 " 77 M 120 x
35 # 78 N 121 y
36 $ 79 O 122 z
37 % 80 P 123 {
38 & 81 Q 124 |
39 ’ 82 R 125 }
40 ( 83 S 126 ~
41 ) 84 T 127 del
42 * 85 U
^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 characteris-
tics, INFORMIX-4GL uses the information in the termcap
file 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 files
that contain additional capabilities for many common ter-
minals (such as the Wyse 50 and the Televideo 950). These
capabilities include intensity-change or color-change
descriptions or both. This appendix describes these capabil-
ities, 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

I
with the information in your terminal manual, to modify
the contents of your termcap file or terminfo files. 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 file is placed in
the etc subdirectory of $INFORMIXDIR. This file is a superset of an operating
system termcap file. The Informix termcap file contains additional capabili-
ties for many terminals. You may want to modify this file further in the fol-
lowing instances:
• The entry for your terminal has not been modified to include color-
change and intensity-change capabilities.
• You want to extend function key definitions.
• 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 Definition

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 terminal’s capabilities. There are three types of capabilities:
• Boolean capabilities
• Numeric capabilities
• String capabilities
All termcap entries have the following format:
• ESCAPE is specified as a backslash ( \ ) followed by the letter E, and CTRL
is specified 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 defined 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 Definition

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=Â@^M:k1=ÂA^M:k2=ÂB^M:k3=ÂC^M:k4=ÂD^M:\
:k5=ÂE^M:k6=ÂF^M:k7=ÂG^M:\
:HI=^|:Po=^R:Pe=^T:
Figure I-1 Wyse 50 termcap Entry

Note: Comment lines begin with a pound sign ( # ).

Terminal Names
A termcap entry starts with one or more names for the terminal, each sepa-
rated 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 specific feature. If the Boolean capability is present in the ter-
mcap 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
Figure I-2 Boolean Capabilities for the Wyse 50

Modifying termcap and terminfo I-3

Format of a termcap Definition

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
Figure I-3 Numeric Capabilities for the Wyse 50

Similarly, sg is a numeric capability that indicates the number of character

positions required on the screen for reverse video. The entry :sg#1: indi-
cates that a terminal requires one additional character position when reverse
video is turned ON or OFF. If you do not include a particular numeric capa-
bility, INFORMIX-4GL assumes that the value is zero.

String Capabilities
A string capability specifies 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, cur-
sor 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=Â@^M:k1=ÂA^M:k2=ÂB^M:k3=ÂC^M:

# ce=\Et clear to end of line

# cl=\E* clear the screen
# nd=^L non-destructive cursor right
# up=^K up one line
#
# so=\EG4 start stand-out
# se=\EG0 end stand-out
#

I-4 Modifying termcap and terminfo

Extending Function Key Definitions

# ku=^K up arrow key

# kd=^J down arrow key
# kr=^L right arrow key
# kl=^H left arrow key
#
# k0=Â@^M function key F1
# k1=ÂA^M function key F2
# k2=ÂB^M function key F3
# k3=ÂC^M function key F4
Figure I-4 String Capabilities for the Wyse 50

Extending Function Key Definitions

INFORMIX-4GL recognizes function keys F1 through F36. These keys corre-
spond 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 first eight function keys send the characters shown in Figure I-5.
Function Key termcap Entry
F1 k0=Â@^M
F2 k1=ÂA^M
F3 k2=ÂB^M
F4 k3=ÂC^M
F5 k4=ÂD^M
F6 k5=ÂE^M
F7 k6=ÂF^M
F8 k7=ÂG^M
Figure I-5 Function Key Entries for the Wyse 50

You can also define keys that correspond to the following capabilities:
• Insert line (ki)
• Delete line (kj)
• Next page (kf)
• Previous page (kg)
If these keys are defined in your termcap file, 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

INFORMIX-4GL uses characters defined in the termcap file to draw the bor-
der of a window. If no characters are defined in this file, INFORMIX-4GL uses
the hyphen ( - ) for horizontal lines, the vertical bar ( | ) for vertical lines, and
the plus sign ( + ) for corners.
The termcap file provided with INFORMIX-4GL contains border character
definitions for many common terminals. You can look at the termcap file to
see if the entry for your terminal has been modified to include these defini-
tions. If your terminal entry does not contain border character definitions, or
if you want to specify alternative border characters, you or your system
administrator can modify the termcap file.
Perform the following steps to modify the definition for your terminal type
in the termcap file:
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 INFOR-
MIX-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 indi-
cated 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
Figure I-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 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 file before you edit it. You
can use the TERMCAP environment variable to point to whichever copy of the
termcap file 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
file, ESCAPE is represented as a backslash ( \ ) followed by the let-
ter E; CTRL is represented as a caret ( ^ ). For example, the Wyse
50 escape sequence ESC-H CTRL-B is represented as \EH^B.
ge The escape sequence for leaving graphics mode. For example, the
Wyse 50 escape sequence ESC-H CTRL-C is represented as \EH^C.
gb 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
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 follow-
ing information in the termcap entry for the Wyse 50:
:gs=\EH^B:\ # sets gs to ESC H CTRL B
:ge=\EH^C:\ # sets ge to ESC H CTRL C
:gb=2135z6:\ # 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 INFOR-
MIX-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 file when you
specify a window border in an OPEN WINDOW statement.

Adding Color and Intensity

Many of the terminal entries in the Informix termcap file (in the etc subdirec-
tory of $INFORMIXDIR) have been modified to include color or intensity
capabilities or both. You can view the termcap file 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 doesn’t, 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 files 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

Number Color Terminal Monochrome Terminal

0 WHITE NORMAL
1 YELLOW BOLD
2 MAGENTA BOLD
3 RED BOLD†
4 CYAN DIM
5 GREEN DIM
6 BLUE DIM†
7 BLACK INVISIBLE
Figure I-7 Color-Monochrome Correspondence

The background for colors is BLACK in all cases. In the Figure I-7, the † signi-
fies that, if the keyword BOLD is indicated as the attribute, the field will be
RED on a color terminal, or if the keyword DIM is indicated as the attribute,
the field 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 file named colornames in your cur-
rent 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 file
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) Color number between 0 and 7 (see Figure I-7)
Parameter 2 (p2) 0 = Normal; 1 = Reverse
Parameter 3 (p3) 0 = No-Blink; 1 = Blink
Parameter 4 (p4) 0 = No-Underscore; 1 = Underscore
ZA uses the values of these four parameters and a stack machine to deter-
mine which characters to send to the terminal. The ZA function is called and
these parameters are evaluated when a color or intensity attribute is encoun-
tered 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 define 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 under-
stand how to define 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 opera-
tions are often necessary and, by storing the display attributes in static stack
machine registers (named a through z), you can achieve terminal-specific
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 oper-
ating 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.
%2d 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 termi-
nal. 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.
%3d 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.
%c pops a single character from the stack and sends it to the terminal.

Operators That Manipulate the Stack

%p[1-9] pushes the value of the specified 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 specified vari-
able. 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´ pushes a single character on the stack. For example, %´k´
pushes k on the stack.
%{n} 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 specified 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.
%+ 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.
%m 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 Decimal

0 1 1 0 0 = 12

1 0 1 0 1 = 21

------------------------- and

0 0 1 0 0 = 4
%| Bit-or. For example, %{12}%{21}%| is equivalent to (12 or 21)
and produces a result of 29.

Binary Decimal

0 1 1 0 0 = 12

1 0 1 0 1 = 21

------------------------- or

1 1 1 0 1 = 29
%^ Exclusive-or. For example, %{12}%{21}%^ is equivalent to (12
exclusive-or 21) and produces a result of 25.

Binary Decimal

0 1 1 0 0 = 12

1 0 1 0 1 = 21

------------------------- exclusive or

1 1 0 0 1 = 25
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 Decimal

0 0 0 1 1 0 0 1 = 25

---------------------------- Complement

1 1 1 0 0 1 1 0 = -26

Logical Operators
The following logical operators pop the top two values from the stack, per-
form 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 per-
forms 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, INFOR-
MIX-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 Description
%d write pop() in decimal format
%2d write pop() in 2-place decimal format
%3d write pop() in 3-place decimal format
%c write pop() as a single character

%p[1-9] push ith parameter

%P[a-z] pop and store variable
%g[a-z] get variable and push on stack
%’c’ push char constant
%{n} push integer constant
%S[a-z] pop and store static variable
%G[a-z] 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())
%m 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-if’s are possible (c’s are conditions):
%? c1 %t...%e c2 %t...%e c3 %t...%e...%;
nested if’s allowed.

all other characters are written to the terminal;

use ’%%’ to write ’%’.
Figure I-8 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 Normal
ESC G 1 blank(invisible)
ESC G 2 blink

ESC G 4 Reverse
ESC G 5 Reverse and blank
ESC G 6 Reverse and blink

ESC G 8 Underscore
ESC G 9 Underscore and blank
ESC G : Underscore and blink

ESC G < Underscore and reverse

ESC G = Underscore, reverse, and blank
ESC G > Underscore, reverse, and blink
Figure I-9 Wyse Escape Sequences

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 #print EG
%’0’ #push ’0’ (normal) on the stack
%?%p1%{7}%=%t%{1}%| #if p1 = 7 (invisible), set
#the 1 bit (blank);
%e%p1%{3}%> #if p1 > 3 and < 7, set the 64 flag (dim);
%p1%{7}%<%&%t%{64}%| #
%;%; #
%?%p2%t%{4}%|%; #if p2 is set, set the 4 bit (reverse)
%?%p3%t%{2}%|%; #if p3 is set, set the 2 bit (blink)
%?%p4%t%{8}%|%; #if p4 is set, set the 8 bit (underline)
%c: #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 first 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, incre-
mented 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; #print lead-in
%?%p1%{0}%=%t%{7} #encode color number (translate
%e%p1%{1}%=%t%{3} # from Figure I-7 to the number
%e%p1%{2}%=%t%{5} # for the ID231)
%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 #if p2 is set, print ’30’ and
# ’40’ + color number (reverse)
%e40;%{30}%+%2d%; # else print ’40’ and
# ’30’ + color number (normal)
%?%p3%t;5%; #if p3 is set, print 5 (blink)
%?%p4%t;4%; #if p4 is set, print 4 (underline)
m #print ’m’ to end character
# sequence
Figure I-10 Sample ZA String for ID231

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
Figure I-11 Concatenated ZA String for ID231

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 usu-
ally the same value as for the sg entry.

The colornames File

You can create a colornames file if you want to change the default assignment
of the names of colors. A colornames file is an ASCII file that changes the key-
words that you use to write INFORMIX-4GL programs. It does not affect the
colors produced by your terminal. The format for the colornames file fol-
lows:
name number
... ...

Explanation
name is the identifier of a color.
number 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
file. You cannot assign the same name to more than one number.
3. Unless you redefine them in the colornames file to have a different num-
ber, 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 file to set up the default assignment of names to
color numbers, colornames would look as follows:
WHITE 0
YELLOW 1
MAGENTA 2
RED 3
CYAN 4

I-18 Modifying termcap and terminfo

The colornames File

GREEN 5
BLUE 6
BLACK 7
If you wanted to change CYAN to AQUA and MAGENTA to ORANGE as color
names, set colornames as follows:
AQUA 4
ORANGE 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 reas-
sign 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 num-
ber 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 doc-
umented 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). INFOR-
MIX-4GL uses the information in terminfo to draw window borders, define
function keys, and display certain intensity attributes.
You may want to modify a file in the terminfo directory in the following
instances:
• You want to extend function key definitions.
• 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 file, 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 file for each terminal name that is
defined. Each file 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 terminal’s capabilities. There are three types of capabilities:
• Boolean capabilities
• Numeric capabilities
• String capabilities
All terminfo entries have the following format:
• ESCAPE is specified as a backslash ( \ ) followed by the letter E, and CTRL
is specified 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,
Figure I-12 Wyse 50 terminfo Entry

Note: Comment lines begin with a period ( . ).

Terminal Names
A terminfo entry starts with one or more names for the terminal (each sepa-
rated 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 five-character code that indicates whether
or not a terminal has a specific 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
Figure I-13 Boolean Capabilities for the Wyse 50

Numeric Capabilities
A numeric capability is a two- to five-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
Figure I-14 Numeric Capabilities for the Wyse 50

String Capabilities
A string capability specifies a sequence that can be used to perform a terminal
operation. A string capability is a two- to five-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, cur-
sor 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=Â@^M,kf1=ÂA^M,kf2=ÂB^M,kf3=ÂC^M,

. el=\Et clear to end of line

. clear=\E* clear the screen
. cufl=^L non-destructive cursor right
. cuul=^K up one line
.
. smso=\EG4 start stand-out
. rmso=\EG0 end stand-out
.

I-22 Modifying termcap and terminfo

Extending Function Key Definitions

. kcuul=^K up arrow key

. kcudl=^J down arrow key
. kcufl=^L right arrow key
. kcubl=^H left arrow key
.
. kf0=Â@^M function key F1
. kf1=ÂA^M function key F2
. kf2=ÂB^M function key F3
. kf3=ÂC^M function key F4
Figure I-15 String Capabilities for the Wyse 50

Extending Function Key Definitions

INFORMIX-4GL recognizes function keys F1 through F36. These keys corre-
spond 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 first eight
function keys send the characters shown in Figure I-16.
Function Key terminfo Entry
F1 kf0=Â@^M
F2 kf1=ÂA^M
F3 kf2=ÂB^M
F4 kf3=ÂC^M
F5 kf4=ÂD^M
F6 kf5=ÂE^M
F7 kf6=ÂF^M
F8 kf7=ÂG^M
Figure I-16 Function Key Entries for the Wyse 50

You can also define keys that correspond to the following capabilities:
• Insert line (kill)
• Delete line (kdll)
• Next page (knp)
• Previous page (kpp)
If these keys are defined in your terminfo file, 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

INFORMIX-4GL uses characters defined in the terminfo files to draw the bor-
der of a window. If no characters are defined in this file, 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 file (using infocmp) to see if the entry for
your terminal includes these definitions. (Look for the acsc capability,
described later in this section.) If the file for your terminal does not contain
border character definitions, or if you want to specify alternative border char-
acters, you or your system administrator can modify the terminfo source file.
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 file 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 INFOR-
MIX-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 indi-
cated 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

Windown 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
Figure I-17 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 file for your terminal. (You can decompile it
using infocmp redirected to a file.)
Note: You may want to make a copy of your terminfo directory before you edit
files. 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
file, ESCAPE is represented as a backslash ( \ ) followed by the let-
ter 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

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
Figure I-18 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 terminal’s 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 capa-
bility would be set as shown in Figure I-19.
acsc=l2m1k3j5qzx6
Figure I-19 Wyse 50 acsc setting

4. Use tic to recompile the modified terminfo file. See your operating sys-
tem 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, . sets smacs to ESC H CTRL B
rmacs=\EH^C, . sets rmacs to ESC H CTRL C
acsc=l2m1k3j5qzx6, . 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, win-
dow borders would be drawn using underscores ( _ ) for horizontal lines, ver-
tical 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 file 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 info-
cmp.
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 $INFOR-
MIXDIR/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 identifies 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 lit-
eral, appears throughout this appendix (except as noted),
but character strings (which omit the data type and field
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 pre-
sented here are fragmentary. That is, they do not include the
DATETIME Columns

full syntax necessary for an executable statement. (The section“Data Manip-

ulation 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 specific point in time. The DATETIME data type
is composed of a contiguous sequence of fields that represent each compo-
nent of time that you want to record. This is the syntax for defining a
DATETIME column or program variable:
identifier DATETIME first TO last
Here first and last are fields taken from the following list:
Field Valid Entries
YEAR A year, numbered from 1 to 9999.
MONTH A month, numbered from 1 to 12.
DAY A day, numbered from 1 to 31, as appropriate to the month in question.
HOUR An hour, numbered from 0 (midnight) to 23.
MINUTE A minute, numbered from 0 to 59.
SECOND A second, numbered from 0 to 59.
FRACTION A fraction of a second with up to five 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 fields from YEAR to
FRACTION. It can be a subset of fields, or even a single field (if first and last
are identical). You can define a DATETIME column or variable to include only
the fields that you need. For example, you can specify MONTH TO HOUR to
include only MONTH, DAY, and HOUR. Since the fields are contiguous, they
include all fields from first to last in the sequence listed above. But you cannot
specify HOUR TO YEAR, because first 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 first field 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 fol-
lowing 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 appli-
cation requires that DATETIME inserts span months in this way, always define
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 fields, and a list of the first and last fields that you are specifying.
(A later section of this appendix describes character string formats.)
Just as you can define a DATETIME column or variable to be only a subset of
all possible fields, you can also specify values that contain just a subset of the
declared fields 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 defined as YEAR TO MINUTE. Each value, however, must always contain
information for a contiguous sequence of fields. 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 fields than the defined column or vari-
able, the value that you enter is automatically expanded to fill all the defined
fields. If you omit a more significant field (that is, a field of a larger unit than
any value that you supply), that field is automatically filled with the system
date. In the previous example, YEAR is omitted, so the current year is auto-
matically inserted into your entry. Alternatively, if you omit a less significant
field, that field is filled 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 field 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 INTERVAL Data J-3

Specifying DATETIME Values

Even though the column mytime has a defined precision of YEAR to MINUTE,
you can supply information for only MONTH to HOUR. The entered value is
automatically expanded to fill 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 automati-
cally, along with zeros for the MINUTE field.
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 fol-
lowing 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 difficulties during months
with fewer than 31 days, do not create DATETIME columns or variables with a first
precision of DAY, and do not enter DATETIME values with DAY as the field of
largest precision.
When you enter a DATETIME literal, you must include a qualifier that specifies
both the first (largest) and last (smallest) field in the value to be entered.
Including the qualifier is necessary because, as noted earlier, the value that
you are entering can contain fewer fields than defined for that column or
variable. Acceptable keywords for the first and last fields are identical to the
list of valid DATETIME fields displayed previously.
A valid entry contains the DATETIME name, the values to be entered, and the
field qualifier. Use the syntax first-field TO last-field to qualify the DATETIME
value. For example, in the following entry, YEAR TO FRACTION indicates that
values for all possible fields are included in the values listed between the
parentheses. The order of entry and the type of delimiter identify which
value corresponds to each field.
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 fields:
DATETIME (89-8-16) YEAR TO DAY
DATETIME (16 12:23) DAY TO MINUTE
DATETIME (21.234) SECOND TO FRACTION
DATETIME (32) SECOND TO SECOND
DATETIME (.0032) FRACTION TO FRACTION(4)
When YEAR is given as a two-digit number, as in the first example, it is auto-
matically 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 field, the first and last qualifiers are the
same. If the first and last qualifiers are both FRACTION, you specify the preci-
sion only for the last field.
Values for the fields are written as integers and are separated by delimiters.
All field values are two-digit integers, except for the YEAR (four digits) and
FRACTION (n digits) fields. The following delimiters are used with
DATETIME values:

Delimiter Placement in DATETIME Expression

hyphen ( - ) Between the YEAR and MONTH, and between the MONTH and
DAY portions of the value.
space ( ) Between the DAY and HOUR portions of the value.
colon ( : ) Between the HOUR and MINUTE, and MINUTE and SECOND
portions of the value.
period ( . ) Between the SECOND and FRACTION portions of the value.
You use the same delimiters when DATETIME values are expressed as char-
acter strings.

INTERVAL Columns
Like the DATETIME data type, the INTERVAL data type is composed of a con-
tiguous sequence of fields. Here is the syntax for defining an INTERVAL
column:
identifier INTERVAL first TO last
Here first and last are fields taken from one of the following two lists:
Field Valid Entries
YEAR A number of years.
MONTH A number of months.
OR

Working with DATETIME and INTERVAL Data J-5

Specifying INTERVAL Values

DAY A number of days.

HOUR A number of hours.
MINUTE A number of minutes.
SECOND A number of seconds.
FRACTION A fraction of a second, with up to five 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 define an INTERVAL column to include
only the fields 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 specifically 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 col-
umn need not include all the declared fields. For example, you can enter a
value consisting of HOUR, MINUTE, and SECOND fields into a column
defined as DAY TO SECOND. A value must always consist, however, of a con-
tiguous sequence of fields. 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 qualifier
that specifies both the first (largest) and last (smallest) fields in the value, just
as for DATETIME values. In addition, you can specify the precision of the first
field (and of the the last field if it is FRACTION). Acceptable qualifiers for the
first field and last field are identical to the list of INTERVAL fields previously
displayed, with the same restriction that YEAR and MONTH cannot be com-
bined with the smaller fields.
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
field qualifier. 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 specific
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 field, the first and last qualifiers are the same.
If the first and last qualifiers are both FRACTION, you can only specify the
precision in the last field.
The first field in an INTERVAL value can be up to nine digits in size (except
for FRACTION, which cannot be more than five digits), but if the value is
greater than the default number of digits allowed for that field, you must
explicitly identify the number of significant digits in the value you are enter-
ing. By default, you are allowed up to four digits in a year, three digits in a
fraction, and two digits in all other fields. If you need more digits than the
default, enter the number of required digits (between parentheses) after the
field qualifier.
INTERVAL (10000-2) YEAR(5) TO MONTH
INTERVAL (127) MONTH(3) TO MONTH
INTERVAL (365 0:23) DAY(3) TO MINUTE
INTERVAL (1421 36:25:54.93721) DAY(4) TO FRACTION(5)
The first example illustrates how you can specify a span of 10,000 years by
including the number five (5) after the YEAR. The second example allows a
three-digit MONTH entry. Notice that the number is attached to the first qual-
ifier. You will get a syntax error if you attach the number to the last qualifier.
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 field in order to enter a value just for MINUTE.
The last example shows how you can specify the precision of both first and
last when FRACTION is the last field.
Non-default precisions are a feature of INTERVAL data. An error results if
you use this notation to specify any DATETIME field 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 field. Note the following examples:
INTERVAL (5-13) YEAR TO MONTH
INTERVAL (6-1) YEAR TO MONTH
The first 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 INTERVAL Data J-7

DATETIME and INTERVAL Values as Character Strings

The values for the fields are written as integers and are separated by delimit-
ers. The following delimiters are used with INTERVAL values:
Delimiter Placement in INTERVAL Expression
hyphen ( - ) Between the YEAR and MONTH portions of the value.
space ( ) Between the DAY and HOUR portions of the value.
colon ( : ) Between the HOUR and MINUTE, and MINUTE and SECOND
portions of the value.
period ( . ) 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 specified as character strings are automatically converted into
DATETIME or INTERVAL values. You can use character strings whenever you
specify information for all fields defined 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 defined fields. You cannot use character strings to enter DATETIME or
INTERVAL values for a subset of fields, because this produces ambiguous val-
ues. If the character string does not contain information for all fields, 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 defined as YEAR TO DAY. Entering only these values
is appropriate in the first 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 infor-
mation 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 defined as DAY TO SECOND. The first INSERT
statement simply pads the value with zeros for YEAR and SECOND. The sec-
ond 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 quan-
tity of a specified unit of time (identified 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
specific 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 Data Type of
Operand 1 Operator Operand 2 Result
Datetime - Datetime Interval
Datetime + or - Interval Datetime
Interval + Datetime Datetime
Interval + or - Interval Interval
Datetime - CURRENT Interval
CURRENT - Datetime Interval
Interval + CURRENT Datetime
CURRENT + or - Interval Datetime
Datetime + or - UNITS Datetime
Interval + or - UNITS Interval
Interval * or / Number Interval

Working with DATETIME and INTERVAL Data 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 val-
ues, 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 find 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 first DATETIME value determines the
field precision for the result. If the second DATETIME value has fewer fields
than the first, the shorter value is automatically extended to match the longer
one. If the second DATETIME value has more fields than the first (regardless
of whether the precision of the extra fields is larger or smaller than those in
the first value), the additional fields 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 first example, no MINUTE field 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 first.

J-10 Working with DATETIME and INTERVAL Data

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 subtract-
ing, however, the DATETIME or DATE value must come first.
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 first example that follows moves the date ahead by three
years and five months. The second example moves the value back by 12
hours. This result, however, is presented as 720 minutes, a three-digit num-
ber. Since this precision exceeds the default of two digits, you must explicitly
define the first qualifier 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 field
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 arith-
metic 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
first example that has a precision from YEAR to DAY. You can perform this cal-
culating 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 first operand.

Working with DATETIME and INTERVAL Data J-11

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
qualifier 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 fields 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 qualified in the range
YEAR to MONTH, or else both must be in the range DAY to FRACTION. Within
these ranges, the qualifiers 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 first 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 qualifiers (in parentheses) to alert
the engine that the MINUTE and FRACTION in the first 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

CURRENT is a keyword that evaluates to the current date and time. You can
use it in place of a specific DATETIME value. The following examples of
expressions with CURRENT assume that CURRENT is executed when the sys-
tem 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 first value determines the precision of output when
using DATETIME values. In the first example, the precision used for CUR-
RENT matches the first 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-field INTERVAL values is to use the
UNITS keyword. It allows you to specify quickly amounts of a field (for exam-
ple, number of years) that you want to add to or subtract from a DATETIME
or INTERVAL value. UNITS has the following syntax:
number UNITS field-name

Working with DATETIME and INTERVAL Data J-13

Multiplying or Dividing INTERVAL Values

where number is the amount and field-name is the type of field. 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 field is added to or subtracted
from an INTERVAL or DATETIME value. Note that the second and third exam-
ples produce the same results as before. This is because manipulating single-
field 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 field. 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 first 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 final 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 final 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 first example updates all rows by a constant INTERVAL value. The sec-
ond example deletes the rows that are more than a year old. The third exam-
ple selects all rows for a given one-year period. The final example includes a
derived field 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 INTERVAL Data 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 result is INTERVAL
DATETIME - DATE result is INTERVAL
DATE +/- INTERVAL result is DATETIME
In these cases, DATE values are first 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
first 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 for-
mat, 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" [, qualifier])

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 INTERVAL Data 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: file is not open.

Corrective Action: Check that the ISAM file has been
opened using the isopen call, or that you have not tried to
write to a ISAM file 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 ele-
ment. (There is a maximum of 8 parts and 120 characters to each key
descriptor.)

-104 Description of Error: ISAM error: too many files open.

Corrective Action: The maximum number of files that can be open at one
time would be exceeded if this request were processed. Reduce the number
of open files by breaking your program up into two or more parts. The max-
imum number of open files per process is 20.

-105 Description of Error: ISAM error: bad ISAM file format.

Corrective Action: The format of the ISAM file has been corrupted. Run the
bcheck utility on the file, and it will try to repair damaged indexes. If bcheck
cannot repair the file, you will need to reload your data from a backup
medium.

-106 Description of Error: ISAM error: non-exclusive access.

Corrective Action: You must first open the file with exclusive access when
you add or delete an index.

-107 Description of Error: ISAM error: record is locked.

Corrective Action: The record or file requested by this call cannot be
accessed because it has been locked by another user. Wait a moment and re-
enter your request.
If you are certain that the table is not in use and your system uses
tablename.lok files, you may need to empty the contents of this file. (This file
contains information about which rows of the table are being used at any one
time. It is normally emptied when a user finishes accessing the table. On occa-
sion, the file is not emptied and, as a result, no one will be able to use the
table.) You can copy the ‘‘file’’ /dev/null into this file 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 defined. You will need to delete this existing index before defining
another.

2 Error Messages
-109 Description of Error: ISAM error: the key is the file’s 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 file.

Corrective Action: The beginning or end of the file 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 specified 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 first perform a query and obtain
a current list.

-113 Description of Error: ISAM error: the file 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 files, you may need to empty the contents of this file. (This file
contains information about which rows of the table are being used at any one
time. It is normally emptied when a user finishes accessing the table. On occa-
sion, the file is not emptied and, as a result, no one will be able to use the
table.) You can copy the ‘‘file’’ /dev/null into this file to remove all locks on
rows in the table. Be certain no processes are accessing the locked table before
emptying the tablename.lok file. Contact your System Administrator about
this action.

-114 Description of Error: ISAM error: the file name is too long.
Corrective Action: Reduce the filename length to ten or fewer characters.

-116 Description of Error: ISAM error: cannot allocate memory.

Corrective Action: Insufficient 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 3
-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 file.

Corrective Action: Check that the log file exists, that you are using the cor-
rect pathname, and that you have operating system read and write permis-
sions on the file.

-121 Description of Error: ISAM error: cannot write log file record.
Corrective Action: Check that you have operating system write permission
on the file and that sufficient disk space is available to add to the file.

-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 data-
base with transactions. Make sure that you have created or started the data-
base 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 first exe-
cute 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 files on the network
using NFS.

4 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 num-
ber 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 fields of the table smaller or create multiple
tables with fewer fields.

-133 Description of Error: ISAM error: audit trail exists.

Corrective Action: You cannot cluster a file with an audit trail. If you want
to cluster the file, you must first drop the audit trail.

-134 Description of Error: ISAM error: no more locks.

Corrective Action: The shared memory parameter for the maximum num-
ber 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 5
-135 Description of Error: ISAM error: tblspace does not exist
Corrective Action: Check whether the tblspace number is correct. (INFOR-
MIX-OnLine)

-136 Description of Error: ISAM error: no more extents

Corrective Action: Use the DB-Monitor to add more disk space. (INFOR-
MIX-OnLine)

-137 Description of Error: ISAM error: chunk table overflow

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 overflow

Corrective Action: There are too many dbspaces. Reinitialize INFOR-
MIX-OnLine to allow for more dbspaces. (INFORMIX-OnLine)

-139 Description of Error: ISAM error: logfile table overflow

Corrective Action: There are too many logfiles. Reinitialize INFOR-
MIX-OnLine to allow for more logfiles. (INFORMIX-OnLine)

-141 Description of Error: ISAM error: tblspace table overflow

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: overflow 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 transac-
tion 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, first reinitialize
INFORMIX-OnLine with a mirror for the root dbspace, then mirror other
dbspaces. (INFORMIX-OnLine)

6 Error Messages
-146 Description of Error: ISAM error: the other copy of this disk is currently dis-
abled 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: Identifier is too long.

Corrective Action: Identifiers must be 18 characters or less. Select a new
identifier 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 con-
trol 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 num-
ber (for example, 125p3 instead of 12503).

Error Messages 7
-204 Description of Error: An illegal floating-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 defining the view.

-206 Description of Error: The specified 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 data-
base built by INFORMIX-SQL or INFORMIX-ESQL/C 1.1. You must first run
dbupdate on your database, which will prepare the database for INFOR-
MIX-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.

8 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 tab-
type = 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 9
-214 Description of Error: Cannot remove file 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 file 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 file.

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 column-
name 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 syn-
onyms 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 file 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 file for new table table-
name.
Corrective Action: The disk may be out of space. Check the ISAM error for
information about the source of the problem.

-223 Description of Error: Duplicate table name table-name in the FROM clause.
Use an alias to rename one of the tables.

-224 Description of Error: Cannot open log file.

Corrective Action: Check the ISAM error for information about the source of
the problem.

-225 Description of Error: Cannot create file 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 tem-
porary 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 file.
Corrective Action: Check the ISAM error for information about the source of
the problem.

-230 Description of Error: Could not read a temporary file.

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 per-
form 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 specified column is derived from an expression or an
aggregate function. Redefine the view.

-235 Description of Error: Character column size is too big.

Corrective Action: Redefine 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 num-
ber.

12 Error Messages
-238 Description of Error: Cannot COMMIT WORK.
Corrective Action: Your log file might be corrupted. Check the ISAM error
number for information about the source of the problem. Contact your Sys-
tem Administrator or Database Administrator if you need assistance with
interpreting the ISAM error number.

-239 Description of Error: Could not insert new row—duplicate value in a

UNIQUE INDEX column.
Corrective Action: The row contains a value which already exists in the col-
umn (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.

-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 file 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 file 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 state-
ment 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: Identifier too long—maximum 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 defining 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 error—invalid statement ID received by the

sqlexec process.
Corrective Action: Make sure that the cursor or object is defined 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

PREPARED—must use cursor.
Corrective Action: Use a cursor for the SELECT statement.

-261 Description of Error: Could not create file 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 file.

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 file.

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 DATA-
BASE 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 ses-
sion, 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 first 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 first 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 col-
umns 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 col-
umns 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 sub-
script range.

-307 Description of Error: Illegal subscript definition.

Corrective Action: Check that you have not reversed the order of the sub-
script delimiters ([3,8] is a valid subscript; [8,3] is invalid) or included a neg-
ative 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 Administra-
tor) 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 specified log file already
exists.
Corrective Action: Select a different name for the log file.

-319 Description of Error: Index does not exist in database file.

Corrective Action: Check the spelling of the index name or check the sysin-
dexes 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 Adminis-
trator) 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. Prefix each column name with the appropriate table name.

-325 Description of Error: Log file must be given a full pathname starting
with a ‘‘/’’.
Corrective Action: Provide the full pathname for the log file.

-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 files in the database directory are deleted, but
the directory remains.
Corrective Action: Remove any non-database files 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 file has been corrupted. You may need to drop and restart the
audit trail.

-333 Description of Error: The audit trail file already exists with a different name.
Corrective Action: You must first drop the existing audit trail file (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 file receiving
the audit trail. Check that you have permission to write to a file 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 specified 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 file name must be given in full directory
path.
Corrective Action: Edit your statement to include the full pathname of the
audit trail file.

-340 Description of Error: Cannot open audit trail file. (operating system error).
Corrective Action: Check that you have operating system read permission
to the file. Contact your System Administrator if you need help with this
action.

-341 Description of Error: Could not read a row from audit trail file.
Corrective Action: The request was not completed (possible operating sys-
tem 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 file 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 file has been corrupted. You may
need to drop and restart the audit trail.

-344 Description of Error: Cannot delete row—row 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 file has been corrupted. You may
need to drop and restart the audit trail.

-345 Description of Error: Cannot update row—row 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 file 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 first 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 specified 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 file for table.
Corrective Action: Check the ISAM error for information about the source of
the problem.

-356 Description of Error: Table table-name specified in both main query and
subquery.
Corrective Action: The statement is ambiguous because a column cannot be
identified 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
modified (for example, a column has been dropped, a data type has been
modified, 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 specified.
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 pre-
cision (total number of digits). You must correct one of the following
conditions:
DECIMAL ( m, n) where n > m
MONEY ( m, n) where n > m
MONEY ( 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 first 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 file for transaction.

Corrective Action: Check the ISAM error for information about the source of
the problem.

-376 Description of Error: Log file already exists.

Corrective Action: Select an alternate name for the log file.

-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 file.

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 specified for view
and select clause.
Corrective Action: Check the number of columns in the view definition 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 definition 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 error—unexpected 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 pre-
served 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 file.

Corrective Action: You cannot edit the log file.

-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 first 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 file exists on the specified node, or that the specified node is
accessible to you.

-421 Description of Error: Unknown service for execution of remote sqlexec.

Corrective Action: The /etc/services file 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 first 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 Tech-
nical 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 float 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 Tech-
nical Support Department.

-433 Description of Error: Type money does not match size.

Corrective Action: This is an internal error. Please notify the Informix Tech-
nical Support Department.

-434 Description of Error: Type decimal does not match size.

Corrective Action: This is an internal error. Please notify the Informix Tech-
nical 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 state-
ment 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 fit 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 file exists and that it has the correct
permissions.

-462 Description of Error: File close error.

Corrective Action: Verify that the file exists and that it has the correct
permissions.

-463 Description of Error: File read error.

Corrective Action: Verify that the file exists and that it has the correct
permissions.

34 Error Messages
-464 Description of Error: File write error.
Corrective Action: Verify that the file 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 first
alter the existing cluster index to NOT CLUSTER before creating a new clus-
tered 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 num-
ber 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 defined. 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 files.

-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 file 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 fields is too large or there are too
many parts in the index.
Corrective Action: Reduce the number of fields or the size of the fields 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 database—no 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 specific 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 identifier on the statement, and declare
a cursor on that identifier.

-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 definition to be sure that no
column is specified more than once in a composite UNIQUE CONSTRAINT.

-543 Description of Error: ESCAPE character must be only one character.

Corrective Action: Check your ESCAPE definition to verify that you have
only specified 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 file.

-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) specified 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 exist-
ing synonym. You can look at the systables table to find 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 func-
tions 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 first 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 ver-
ifying 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 conver-
sion.
Corrective Action: Someone else might have an exclusive lock on the data-
base, or someone else might be accessing the database. Wait to run the data-
base 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.

-566 Description of Error: Cannot initiate sort.

-567 Description of Error: Cannot write sorted rows.

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 specified 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 sub-
query 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 specified 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 prefix system catalog names with ‘‘informix’’.) Check the spell-
ing 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.

-602 Description of Error: Cannot open blob.

-603 Description of Error: Cannot close blob.

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.

-606 Description of Error: Invalid blob space name.

Corrective Action: Check the name of the blobspace in which you are stor-
ing 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 first
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 can’t 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.

-621 Description of Error: Unable to update new lock level.

-622 Description of Error: Error on locating UNIQUE index index-name.

Error Messages 45
-623 Description of Error: Unable to find 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.

-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 file for run (operating system error).
Corrective Action: Check that the file 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 file. 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 file (check file permissions).

Corrective Action: Check that you have operating system read permission
to access the file. Contact your System Administrator if you need help with
this action.

-817 Description of Error: Cannot write file (check file 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 specified 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 specified in your DBPATH
environment variable.

-832 Description of Error: Error(s) found in form specifications.

Corrective Action: Edit the form specification file following the prompts
provided by FORM4GL. Recompile the form specification.

-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 insufficient 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 files 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 file.

Corrective Action: Check that you have operating system read permission
to access the file. Contact your System Administrator if you need help with
this action.

-843 Description of Error: Cannot write temp file.

Corrective Action: Check that you have operating system write permission
to create a file 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 file is not equal to the
number of columns.
Corrective Action: Check that the number of values in the load file equals
the number of columns in the table.

48 Error Messages
-847 Description of Error: Error in load file line line-no.
Corrective Action: See the accompanying error message for information
about the source of the problem. Check the load file.

-851 Description of Error: Cannot drop file (check file permissions.)

Corrective Action: Check the access permissions on the file 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 file. Check the syntax of your SQL state-
ments and retry the statement.

-900 Description of Error: Cannot read network user authorization file.

Corrective Action: Check that the network user authorization file 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 file.
Corrective Action: Add the user to the network authorization file.

-902 Description of Error: User not authorized or too many entries in

authorization file.
Corrective Action: Requires a version configured for more users. Contact
Informix Software for assistance.

-904 Description of Error: Authorization file 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 prop-
erly. 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 Programmer’s 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 files.

-931 Description of Error: Cannot locate service-name service/tcp service in

/etc/services.
Corrective Action: Check the /etc/services file 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 specified 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 configured properly to accept this user name. Consult
your machine and network user manuals for assistance.

-952 Description of Error: User’s password is not correct for the remote host.
Corrective Action: Check your /etc/hosts.equiv file 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 file. 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 file. Consult your net-
work 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 configured 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 file. /etc/hosts.equiv on the remote
host.
Corrective Action: Verify that the client machine name is in the
/etc/hosts.equiv file on the remote host machine.

52 Error Messages
-999 Description of Error: Long transaction aborted.
Corrective Action: Your transaction has either filled up all of the available
logical log space or it was waiting for a lock held by a transaction that filled
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 conflict
with the long transaction again. Increasing the number of logical log files on
your system might also help, if your process is conflicting with other pro-
cesses 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 field name listed in an INPUT, INPUT ARRAY, DISPLAY,
DISPLAY ARRAY, or CONSTRUCT statement does not appear in the form spec-
ification file of the screen form that is currently displayed. Change the field
name in the program or form specification file 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 defines
the screen array in the form specification file. Change the subscript in your
program or make the appropriate modifications to your form specification
file.

-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 spec-
ification file. Change the screen record name in your program or in your form
specification file.

-1109 Description of Error: List and record field counts differ.

Corrective Action: The number of program variables or columns is not the
same as the number of fields in an INPUT, INPUT ARRAY, DISPLAY, DISPLAY
ARRAY, or CONSTRUCT statement. Check the variable-list or column-list and
the field-list to make sure they contain the same number of items.

Error Messages 53
-1110 Description of Error: Form file not found.
Corrective Action: The form file specified in the OPEN FORM statement
could not be found. Make sure that your program can access the form file
specified 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 file specified in an OPEN FORM statement has
been corrupted, or was compiled with an older version of FORM4GL. Recom-
pile the form specification file with the appropriate version of FORM4GL.
Note: Do not specify a file 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 field.

Corrective Action: Please check the entered value and make the necessary
correction.

-1116 Description of Error: Default value from form field cannot be converted to
input variable type.
Corrective Action: The default value in a display field 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 field 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 field name in the NEXT FIELD clause of an INPUT or
INPUT ARRAY statement does not appear in the field-list of the statement.
Change the NEXT FIELD clause or the field-list as appropriate.

-1120 Description of Error: Message file not found.

Corrective Action: The message file specified 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 file specified in the OPTIONS HELP FILE
statement.

-1121 Description of Error: Message number not found in message file.

Corrective Action: A message number in an INPUT, PROMPT, or MENU state-
ment does not appear in the corresponding message file. Change the message
number in your program or add a new message to the file and recompile.

-1122 Description of Error: Incompatible message file.

Corrective Action: The message file specified in the HELP FILE clause of the
OPTIONS statement could not be read. Make sure the OPTIONS HELP FILE
statement specifies a compiled message file that is readable.

-1129 Description of Error: Field in BEFORE/AFTER clause not found in form.

Corrective Action: A field name in the BEFORE or AFTER clause of an INPUT
or INPUT ARRAY statement does not appear in the form specification file of
the screen form that is currently displayed. Change the field name in the pro-
gram or form specification file as appropriate and recompile.

-1130 Description of Error: You cannot have multiple BEFORE clauses for the same
field.
Corrective Action: Combine the BEFORE clauses for the same field in INPUT
or INPUT ARRAY statements.

-1131 Description of Error: You cannot have multiple AFTER clauses for the same
field.
Corrective Action: Combine the AFTER clauses for the same field 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 user’s search crite-
ria 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 specified 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 files. Add the code for the specified func-
tion key to the termcap file, or add the code to your terminal file in the ter-
minfo 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 fit on the screen.

Corrective Action: The window dimensions specified 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 win-
dow. If you are attempting to open the window WITH FORM, you must
reduce the size of the form. (When sizing a window to fit a form, INFOR-
MIX-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 fit on screen. Window is too large.
Corrective Action: The dimensions of the bordered window exceed the lim-
its 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 specified in the WITH clause of
the OPEN WINDOW statement are too small for the form. Either open the win-
dow 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 win-
dow 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 specified 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 fit 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 accom-
modate 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 specified the correct window. You must
first 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 posi-
tive 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 significant 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 significant 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 field.

-1205 Description of Error: Invalid month in date.

Corrective Action: In SQL statements such as INSERT, a month can be repre-
sented as the number of the month (1 through 12). In display fields, a month
can be represented either as the number of the month (1 through 12) or as the
first three letters of the name of the month. Check the value entered in the
DATE column or field.

-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 field.

-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 field.

-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 field 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 fit 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 fit 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 field) in the form specification.

-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 fit in a SMALLFLOAT.
Corrective Action: Enter the appropriate value, depending on the machine
that you use.

-1223 Description of Error: Value will not fit 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 field.

-1227 Description of Error: Message file not found.

Corrective Action: Check to see if you have installed the product correctly.
Alternately, you might be missing a message file. Search for the required mes-
sage file.

-1228 Description of Error: Message number not found in message file.

Corrective Action: You might have a corrupted message file. Retrieve an
uncorrupted message file by re-installing the product (or by re-editing and
recompiling 4glusr.msg, if you changed a message number in that file).

-1229 Description of Error: Incompatible message file.

Corrective Action: Retrieve uncorrupted version of message file by re-
installing the product.

-1230 Description of Error: Bad message file name formulation.

Corrective Action: Check to see if you have entered the correct message file
names.

-1231 Description of Error: Cannot seek within message file.

Corrective Action: Re-install or rebuild your message files.

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 file as a single message, or else that it is mistakenly
reading memory instead of a message file. Make sure that your message file
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 vari-
able. 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 Techni-
cal Support Department.

-1252 Description of Error: Unable to create shared memory. shmget failed.

-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 identi-
fier 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 specified
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
specified 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 first field of datetime or
interval.
Corrective Action: Specify fewer digits. The default precision is two (2)
digits for every field, except year (4) and fraction (3). You can specify a non-
default 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 field 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 separa-
tor, 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 field in a datetime or interval is out of range.

Corrective Action: In an INTERVAL field, the absolute value of any field 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 specific 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 field.

-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 field, entered
too many digits or too many fields, neglected the effect of an EXTEND func-
tion, or made a typing mistake.

Error Messages 63
-1265 Description of Error: Overflow occurred on a datetime or interval
operation.
Corrective Action: Both DATETIME and INTERVAL values are stored inter-
nally as decimals. Your arithmetic operation produced a decimal overflow.
Examine your program logic to see if you can change the sequence or preci-
sion of your operations to avoid the overflow.

-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 fields is described in the suggested actions for error -1263. Some
field in your result (probably the first) 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 opera-
tion to avoid the out-of-range results.

-1268 Description of Error: Invalid datetime qualifier.

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 Techni-
cal 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 fields.

-1271 Description of Error: Missing decimal point datetime or interval.

Corrective Action: Use the decimal point ( . ) to separate the second and frac-
tion fields, 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) specified for the field via the INCLUDE attribute in the form specifi-
cation. Be sure to enter a value that appears in the INCLUDE list in the form
specification file.

-1302 Description of Error: The two entries were not the same—please 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 field 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 field 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 field that has been assigned the PICTURE attribute.

-1304 Description of Error: Error in field.

Corrective Action: The system issues this warning when the user tries to
enter a value in a display field that cannot be converted to the data type of
the corresponding program variable in the INPUT or INPUT ARRAY state-
ment. The user must enter a value in a display field that is compatible with
the data type of the corresponding program variable in the INPUT or INPUT
ARRAY statement.

-1305 Description of Error: This field 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 field that has been assigned the REQUIRED attribute. The
user must enter a value in the required field.

-1306 Description of Error: Please type again for verification.

Corrective Action: The system issues this message during an INPUT or
INPUT ARRAY statement after the user enters a value once in a display field
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 row—the 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 row—it 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 specifies. 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 param-
eters 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 file 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.

Error Messages 67
-1324 Description of Error: A report output file cannot be written to.
Corrective Action: Check that you have WRITE access to the file in the des-
ignated directory. Contact your System Administrator if you need help with
this action.

-1325 Description of Error: PRINT FILE error—cannot open file filename for
reading.
Corrective Action: Check that the specified file 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
specified dimensions.
Corrective Action: Check that the number of subscripts for the array corre-
sponds to the number of dimensions specified in the array definition. Check
that the subscript(s) do not exceed the value(s) specified in the array defini-
tion. Compile with the -a option to check array dimensions.

-1327 Description of Error: An insert statement could not be prepared for insert-
ing 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 specified in the variable definition.

-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 finished 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 file 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 redefined with a
different type or length.
Corrective Action: The lengths and types of global variables in two modules
must be consistent. Make the definitions consistent and recompile the
program.

Error Messages 69
-1338 Description of Error: The function function-name has not been defined 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 file specified.

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: Undefined opcode.

Corrective Action: A function cannot be executed because your p-code file
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 significant 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 significant 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 specified

types.
Corrective Action: Examine your code to make sure that you have specified
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 fields.
Corrective Action: The INFORMIX-4GL editors cannot modify TEXT and
BYTE fields. BLOB values can be modified only by outside programs, such as
spreadsheets, word-processors, and so forth. Use the PROGRAM attribute in
the form specification file to specify the outside program for this field. Press
the exclamation point ( ! ) key to invoke the outside program.

-1355 Description of Error: Cannot build temporary file.

Corrective Action: There is insufficient disk space to build a temporary copy
of the TEXT or BYTE variable.

-1356 Description of Error: Write error on temporary file filename.

Corrective Action: An I/O error occurred while trying to write the tempo-
rary file in which the TEXT or BYTE variable is stored. This can be caused by
insufficient space on the disk, or by file corruption.

-1357 Description of Error: Read error on temporary file filename.

Corrective Action: An I/O error occurred while trying to read the tempo-
rary file in which the TEXT or BYTE variable is stored. This can be caused by
insufficient space on the disk, or by file corruption.

-1358 Description of Error: Write error on blob file filename.

-1359 Description of Error: Read error on blob file filename

Error Messages 71
-1360 Description of Error: No "PROGRAM=" clause for this field.
Corrective Action: This key ( ! ) invokes an editing program that can be
specified by the PROGRAM attribute. If you want to access that editor, you
must first assign the PROGRAM attribute to this field in the ATTRIBUTES sec-
tion of the form specification file, and then use FORM4GL to recompile the
screen form.

-1361 Description of Error: Illegal blob file name. Null names are not permitted.
Corrective Action: You must specify a valid name for the file that contains
this binary large object (BLOB) of data type TEXT or BYTE.

-2013 Description of Error: The output form file filename 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 filename on the
command line (unless you use the -d option to FORM4GL). Carefully reenter
the command, including the filename 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: com-
ments cannot be nested.) Recompile the form specification.

-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 specification.

-2017 Description of Error: The character data value does not convert correctly to
the field 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 (place-
ment of commas, braces, and so on). Recompile the form specification.

-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 col-
umn to DECIMAL type. Recompile the form specification.

-2020 Description of Error: The table table-name could not be opened. The operat-
ing system was asked to open it for writing.
Corrective Action: Check that you have operating system write permission
to create a file in the designated directory. Contact your System Administra-
tor if you need help with this action. Recompile the form specification.

-2021 Description of Error: An illegal color has been specified. 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 specification cannot reference colors by number, nor by names from
the colornames file.

-2022 Description of Error: This identifier exceeds the maximum length for iden-
tifiers, which is 50.
Corrective Action: Check that all field names, field labels, and identifiers are
less than or equal to 50 characters in length. Recompile the form specification.

-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 specification.

-2024 Description of Error: There is already a record record-name specified. 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 defined 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 specification.

-2026 Description of Error: The FORMONLY field field-name does not have a type
specified. A type must be specified if include lists or default values are
specified.
Corrective Action: Include a type specification after the field-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 list-
ing, 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 specification
file 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 Programmer’s Manual for more information.

-2028 Description of Error: The symbol symbol-name does not represent a table
prefix used in this form. It cannot be used here to select record elements.
Corrective Action: Check to make sure that the table prefixes 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 specified 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 specification file where indicated and cor-
rect the error. Recompile the form specification.

-2031 Description of Error: The WORDWRAP attribute can only be specified for
CHAR, VARCHAR and TEXT fields.
Corrective Action: See if you have specified the wrong field tag or column
name, or the wrong data type of a FORMONLY field.

74 Error Messages
-2032 Description of Error: The number above could not be successfully con-
verted 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 fixed
point number) or that it does not contain an error (if a decimal number).
Recompile the form specification.

-2033 Description of Error: The field field-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 specified, 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 field 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 fit on the
first (and subsequent) pages. This happened within your WORDWRAP field.
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 fields.

-2037 Description of Error: The PROGRAM attribute can only be specified for BYTE
and TEXT fields.
Corrective Action: See if you have specified the wrong field tag or column
name, or the wrong data type of a FORMONLY field.

-2038 Description of Error: BLOB fields 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 fields.
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
specification.

-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
specification.

-2042 Description of Error: The usage of a BLOB field in or around the above state-
ment is incorrect.
Corrective Action: You have specified an attribute that does not support
TEXT or BYTE fields, or else your condition for the COLOR attribute cannot be
applied to a BLOB.

-2043 Description of Error: Screen layout exceeds the specified screen width. This
is a warning only.
System Action: Your form successfully compiled.
Corrective Action: According to your explicit or default column specifica-
tion, 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 specified for each
field with each condition.
Corrective Action: Correct your ATTRIBUTE section, so that no condition
assigns multiple colors to the same field.

-2045 Description of Error: The conditional attributes of a 4GL field cannot

depend on the values of other fields.
Corrective Action: Correct your ATTRIBUTE section, so that no field tag
except that of the current field appears in the condition.

-2100 Description of Error: Field field-tag has validation string error, String = char-
acter-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 first line of the specification 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 first line of the form specifica-
tion file, or check that the keyword DATABASE is followed by the database
name or the FORMONLY keyword. Recompile the form specification.

-2810 Description of Error: The name database-name is not an existing database

name.
Corrective Action: Check the spelling of database-name. Check that data-
base-name exists in your current directory or a directory included in your
DBPATH environment variable. Recompile the form specification.

-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 file. Contact your System Administrator if you need help with
this action. Recompile the form specification.

-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 file. Contact your System Administrator if you need help with
this action. Recompile the form specification.

-2820 Description of Error: The label name between brackets is incorrectly given
or the label is missing.
Corrective Action: Check that the field tag ( = label name) exists and is cor-
rectly spelled. Recompile the form specification.

-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 field size of each
field. Insert a right square bracket ( ] ) where appropriate into the form spec-
ification file. Note that a display field cannot be split across lines. For a mul-
tiple-line field to which you assign the WORDWRAP attribute, each segment
must be indicated by delimiters, with the same field tag repeated in each seg-
ment of the field. Recompile the form specification.

-2831 Description of Error: The control block has exceeded the maximum of 20
fields.
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 field place-
ment. 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 defined in the form.
Corrective Action: Check that the field tag label-name is included in both the
SCREEN and ATTRIBUTES sections of the form specification file, or delete the
unnecessary label-name. (This error often accompanies errors -2820 and
-2975.) Recompile the form specification.

-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
specification.
Corrective Action: Be sure all fields in the ATTRIBUTES section appear in the
SCREEN section.

-2844 Description of Error: The column column-name is associated with more than
one field in the form specification.
Corrective Action: You have specified a record element that appears in more
than one field. 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 cre-
ating 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 field field-name is not a member of the table
table-name.
Corrective Action: Be sure the field is a column in the specified 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 specification.

-2856 Description of Error: The TODAY attribute can be assigned only to date
columns.
Corrective Action: Check that the field 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
specification.

-2859 Description of Error: The column column-name is a member of more than

one table—you 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
specification.

-2860 Description of Error: There is a column/value type mismatch for col-

umn-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 exam-
ple, DATE for a date column, or INTEGER for an integer). Recompile the form
specification.

-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 specification.

-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
specification.

-2863 Description of Error: The column column-name does not exist among the
specified tables.
Corrective Action: Check the spelling of the column name or check that
column-name does exist in one of the specified tables. Recompile the form
specification.

Error Messages 79
-2864 Description of Error: The table table-name is not among the specified tables.
Corrective Action: Check the spelling of table-name in the ATTRIBUTES sec-
tion of the file. Check that the table is specified in the TABLES section of your
form. Recompile the form specification.

-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
specification.

-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 field.
Corrective Action: Check that the space provided in the display field is
greater than or equal to the subscripted column size. Recompile the form
specification.

-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 definition 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 first character position on the line. Recom-
pile the form specification.

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
field label.
Corrective Action: The column name column-name appears more than once
in the ATTRIBUTES section of the form specification file. Use the same field
tag (in the SCREEN section) to denote the repeated column, and remove any
duplicate column names from the ATTRIBUTES section. If you want a multi-
ple-line field to display long strings on several lines of the form, use the same
field tag in the SCREEN section for each segment of the field, and assign the
WORDWRAP attribute to that field tag in a single line of the ATTRIBUTES sec-
tion. Recompile the form specification.

-2893 Description of Error: The display field label field-tag appears more than once
in this form, but the lengths are different.
Corrective Action: A field tag ( = display field label) can appear more than
once in the SCREEN section, but in every instance the display fields must have
identical lengths. Edit the field delimiters so that they are of equal length.
Recompile the form specification.

-2895 Description of Error: Display field length of number does not match the
database column length of number. This is a warning only.
Corrective Action: Check that the display field length (included in the
SCREEN section) is equal to the table column size. (This error occurs only in
character fields and with the -v option to FORM4GL.)

-2901 Description of Error: Field field-name contains two conflicting attributes,

attribute1 and attribute2.
Corrective Action: The UPSHIFT and DOWNSHIFT attributes cannot both be
assigned to the same field; 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 first 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 specification file). Subscripts cannot overlap
(for example, [25-49] and [50-75] are acceptable; [25-50] and [50-75] are unac-
ceptable, as character 50 would have to appear twice). Recompile the form
specification.

-2931 Description of Error: There is an error in the format specification.

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 specifications for errors. Recompile the form specification.

-2932 Description of Error: Formats can be specified only for DECIMAL, SMALL-
FLOAT, 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 specified the format on a CHAR, DATETIME,
INTEGER, INTERVAL, or SMALLINT data type. Recompile the form
specification.

-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 field in the form.
Recompile the form specification.

-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 field in the form.

Note: Until this error is corrected, any data displayed in the field might
be truncated.)

-2935 Description of Error: The number of lines specified 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 specified 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 pos-
itive value between 30 and the width (in characters) of your physical screen.

-2940 Description of Error: The column column-name appears both with and with-
out 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 instruc-
tions in the form. Recompile the form specification.

-2944 Description of Error: You may apply the AFTER ADD, UPDATE, QUERY, or
REMOVE commands to a table only—not 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
field field-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 display-
only field field-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 first subscript is one, not zero.
Corrective Action: Edit the form specification file so that the subscript to the
column column-name begins with 1 (and not 0). Recompile the form
specification.

-2951 Description of Error: The left and right delimiters must be specified in a
two-character string.
Corrective Action: When changing the delimiters that INFORMIX-4GL uses
to enclose the display fields in the SCREEN section of a form, you must specify
both the left and right delimiters with one character each. Recompile the form
specification.

Error Messages 83
-2952 Description of Error: In order to use a picture, the picture length must be the
same as the display field length.
Corrective Action: Edit the file so that the length of the picture specified
with the PICTURE attribute equals the display field length in the SCREEN sec-
tion. Recompile the form specification.

-2955 Description of Error: The name field-tag is not a displayed field in this form.
Corrective Action: The display field field-tag has been specified in the
ATTRIBUTES section of the form specification file, but the field-tag is not
included in the SCREEN section of the form. Delete the field-tag from the
ATTRIBUTES section or include it in the SCREEN section. Recompile the form
specification.

-2958 Description of Error: You may have a maximum of ten parameters in a C-

function.
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 col-
umn 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 specification.

-2972 Description of Error: This column cannot be right justified or zero-filled

because its displayed width does not match the actual column width.
Corrective Action: Make sure the field 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
field 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 field label field-tag has not been used.
Corrective Action: The field tag ( = display field label) field-tag present in the
SCREEN section of the form specification file does not correspond to any field
name in the ATTRIBUTES section. Delete field-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 specification.

-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 specification file to specify any necessary table names or
aliases, field 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 can-
not 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 identifier table-alias is defined 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 identifiers 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 specification 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 specification 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 com-
mand line, FORM4GL divides the form by beginning a new page after the last
line that can fit on the first (and subsequent) pages. Your form requires more
than 20 pages.
Redesign and recompile your form, so that the page layout fits on a single
page. Use multiple forms or windows, rather than multiple pages, if you
need to display more fields.

-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 specification file. Recompile the form
specification.

-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 first 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 first. 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 dimen-
sion 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
specifications. (See the description of -2987 for more information.)
To avoid concealing display fields, 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 fields
than can fit on a single page.

86 Error Messages
-2992 Description of Error: The display label field-tag has already been used.
Corrective Action: Each field tag ( = display label) must be unique. Specify
a different field tag. Recompile the form specification.

-2993 Description of Error: There is a circular join path specified 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 Programmer’s 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 specification.

-2997 Description of Error: See error number errno.

Corrective Action: Locate the indicated error message in this appendix.
Recompile the form specification.

-2998 Description of Error: Operating system error error-number: string.

Corrective Action: If the error number is between 1-99, check your UNIX
Programmer’s 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 five levels of nested records can appear in a record
definition. Reduce the number of nested records so that it does not exceed
five.

-4304 Description of Error: A different database has already been declared. If your
program uses a global definition file, it must contain the same database name
as this one.
Corrective Action: Make sure that the database specified in a global defini-
tion file is the same as the database specified in the file 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 data-
base. 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 file filename cannot be opened for
reading.
Corrective Action: Check that the GLOBALS file exists and that you have
operating system read permission for the file. If the GLOBALS file is not in the
current directory, you must specify the pathname of the file from root or
current directory.

88 Error Messages
-4307 Description of Error: The number of variables and/or constants in the dis-
play list does not match the number of form fields in the display destination.
Corrective Action: Check the variable-list and the field-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 fields in the screen input list.
Corrective Action: Check the variable-list and the field-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 state-
ment 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 trail-
ers.
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 defined as a record.
It cannot be used in this fashion.
Corrective Action: You can use the THRU, THROUGH, or .* notations only
with records. Define 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 defined more than
once.
Corrective Action: Make sure that each variable is defined 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
specified database.
Corrective Action: Check the spelling of table-name and make sure that it is
a table in the specified 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 specified database.
Corrective Action: Check the spelling of column-name, and make sure that it
appears in a table of the specified 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 corre-
sponding 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 sub-
string. 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 specified 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 fields.
Corrective Action: Change the type of the variable to INTEGER or SMALLINT
if you want to use it to index display fields.

-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 parame-
ters 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 specified 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 defined
within the function or report.
Corrective Action: You must use the DEFINE statement to declare all param-
eters passed as arguments to a function or report.

-4338 Description of Error: The symbol variable-name has already been defined
once as a parameter.
Corrective Action: Make sure that each parameter is defined 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 specified 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 vari-

able-name because it is not a character or array variable.
Corrective Action: Check the spelling of the variable name. Define vari-
able-name as a character or array variable or remove the subscript, as appro-
priate.

-4344 Description of Error: The variable variable-name cannot be used with sub-
strings 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 vari-
able, 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 (repre-
sented 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 defined 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 defined as a record before you add a suffix (.variable-name) to it.

-4348 Description of Error: This type of aggregate must be applied to an expres-

sion, 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 specified 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 specified 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 first page header has already been specified within
this report.
Corrective Action: Change the FORMAT section of your report so that it con-
tains only one FIRST PAGE HEADER control block.

-4359 Description of Error: An ON EVERY ROW clause has already been specified
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 specified
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 state-
ments 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 defined
variable.
Corrective Action: Make sure that you define the variable in a DEFINE state-
ment 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 specified 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 file.

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-num-
ber, character character-number. The construct is not understandable in its con-
text.
Corrective Action: When INFORMIX-4GL encounters a grammatical error, it
inserts a marker in the .err file 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 specified 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
specified in the PAGE LENGTH statement. Change the page header and trailer
or the page length as appropriate.

-4376 Description of Error: The temporary file filename cannot be created for
writing.
Corrective Action: Check that you have permission to write a file in /tmp or
the directory specified by the DBTEMP environment variable. Check that
there is enough space in the directory where the temporary file will reside.
Contact your System Administrator if you need help with these actions.

-4377 Description of Error: The output file filename cannot be created or opened.
Corrective Action: Check that you have permission to write a file in the
directory where the output file will be created. Contact your System Admin-
istrator if you need help with this action.

-4378 Description of Error: No input file was specified.

Corrective Action: Make sure that you specify an input filename.

-4379 Description of Error: The input file filename cannot be opened.

Corrective Action: Check the spelling of the input filename. Check that the
file exists in the current directory. Check that you have operating system read
permission for the input file.

Error Messages 97
-4380 Description of Error: The listing file filename cannot be created.
Corrective Action: Check that you have operating system write permission
in the directory where the listing file will be created. Contact your System
Administrator if you need help with this action.

-4381 Description of Error: The input file filename has an invalid extension. The
filename must have .4gl as the extension.
Corrective Action: Rename the input file 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 .* short-
hands 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 ele-
ment of any record.
Corrective Action: Check the spelling of element-name and make sure that it
belongs to the specified 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 fields in this report. The
maximum number is eight.
Corrective Action: Reduce the number of ORDER BY fields 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 five 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 field names can be specified only by the field name suffix.
Screen array and screen record elements are not allowed.
Corrective Action: You cannot include a prefix when specifying a field name
in a BEFORE FIELD or AFTER FIELD clause of an INPUT or INPUT ARRAY state-
ment. (A prefix 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 let-
ters in a key list (if a KEY clause for the menu option is present) or by typing
the first 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 specified with a data-
base 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 fit 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 defined 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 vari-
able-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
definition.

-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 con-
trol 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 charac-
ters, 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 abso-
lute 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 identifier that is too long in

the above line.
Corrective Action: Make sure that an alphanumeric identifier 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 defined as INTEGER or SMALLINT.

Error Messages 101

-4413 Description of Error: The label label-name has already been defined within
this MAIN program or function.
Corrective Action: Make sure that each label is defined only once in the
MAIN program or function.

-4414 Description of Error: The label label-name has been used but has never been
defined within the above main program or function.
Corrective Action: Make sure that you define 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 specified 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 can-
not 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 defined 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 defined as a large CHAR variable.

-4420 Description of Error: The number of lines printed in the IF part of an IF-
THEN-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 condi-
tional 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 field.
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 defined as a
record.
Corrective Action: Make sure that the variable is defined as a record before
using it with the THRU, THROUGH, or .* notation.

-4425 Description of Error: The variable variable-name has not been defined LIKE
the table table-name.
Corrective Action: Define 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 field 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 field on a screen form, the
DISPLAY AT statement to display information at a specified 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 field 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 filename in the REPORT TO ‘‘filename’’ 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 licens-
ing information.
Corrective Action: A program compiled using the demonstration version of
INFORMIX-4GL can contain only one module with no more than 150 INFOR-
MIX-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 redefine 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 specified 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 Inter-
rupt key, or CTRL-k where k is any character except a, d, h, l, r, or x. Some sys-
tems 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 pro-
gram. 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 file filename for reading or writing.
Corrective Action: Check that the file filename exists and that you have
permission to read or write to it.

-4452 Description of Error: The function function-name has already been defined.
Corrective Action: Check your code to make sure that the function has not
been defined 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 specification.

-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 spec-
ified by num and recompile the form specification.

-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 file. Correct the attribute statement and recompile the program.

-4461 Description of Error: Line num in the colornames file must have the form
"<color> 0-9".
Corrective Action: The compiler cannot read the colornames file located in
either the current directory or $INFORMIXDIR/incl because a line does not
have the specified format. Check the spelling and syntax for line num in the
colornames file 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 specified 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 specified in the INPUT ARRAY or
DISPLAY ARRAY statement has only one dimension. Remove all other dimen-
sions 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 specified
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 specified
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 specified
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 recom-
pile the program.

-4476 Description of Error: Record members may not be used with database col-
umn substring. Possible misspelling or usage of undefined 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 defined.
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 function’s 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 sub-
scripts 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 field in a screen form cannot be qualified
by an owner name, a site name, or a remote database name. In the TABLES
section of the form specification file, specify a table alias that includes the
qualifier(s). Use this alias in the BY NAME clause of any 4GL statements that
reference fields 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 val-
ues 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 param-
eters 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 error—cannot open file filename for
reading.
Corrective Action: Check that the specified file 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 func-
tion 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 cre-
ated by the p-code compiler. Recompile the program. If the problem recurs,
call your Informix Representative.

-4527 Description of Error: Undefined opcode in function function-name.

Corrective Action: The p-code file 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 file filename starts with a bad magic number. You
may have tried to run a file that was not created by the 4GL p-code compiler.
Corrective Action: The p-code file 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 specified 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 specified by
DBPATH.

-4601 Description of Error: No 4GL module by specified 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 specified by
DBPATH.

112 Error Messages

-4602 Description of Error: No 4GL program by specified 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 specified 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 files to determine the problem. Modify
the appropriate INFORMIX-4GL files and recompile. You can use the vi editor
to edit file.err to look at the error file and use the Module-Modify option to
change the file 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 state-
ments in your program. You may have used a reserved word as an identifier.

-4609 Description of Error: Insufficient 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 stan-
dard syntax for SQL.

-4611 Description of Error: There is no 4GL source available for this program.
Corrective Action: Check the program definition file 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 specified 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 specified 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 Programmer’s Environment. If
syspgm4gl does exist, make sure that it resides in the current directory or in
a directory specified 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 file in a direc-
tory that is not on the device that holds your current directory. Use a system
utility to copy the source file to your current directory (or to a directory on
the current device).

-4618 Description of Error: An error has occurred in accessing the requested file.
Corrective Action: Something prevented your access to the file. This could
be a hardware problem, your file system could be out of disk space, or you
may not have permission to access the file 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 files. Oth-
erwise, you must remove all mention of the .ec files in the program definition.

-4621 Description of Error: An error occurred while writing to output file filename.
Corrective Action: Something prevented your access to the file. This could
be a hardware problem, your file system could be out of disk space, or you
may not have permission to access the file or the directory. Contact your
System Administrator.

-4622 Description of Error: No runable 4GL program by specified name found.

System Action: INFORMIX-4GL prompts you to enter the name of an exist-
ing 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
specified by DBPATH.

-4623 Description of Error: memory allocation error

Corrective Action: The process was unable to acquire the amount of mem-
ory 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 file filename.

Corrective Action: Check the directory listing for this file. It might not exist,
or permissions might be set that prevent the program from reading the file.

-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 file.

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 file.

-4629 Description of Error: Load from file filename failed.

Corrective Action: A conversion error occurred, or there was insufficient
space to complete the load. Check your disk space availability and the file
size.

-4630 Description of Error: Unload to file filename failed.

Corrective Action: A conversion error occurred or there was insufficient
space to complete the load. Check your disk space availability and the file
size.

-4631 Description of Error: Startfield of DATETIME or INTERVAL qualifiers must

come earlier in the time-list than its endfield.
Corrective Action: You may have reversed the order of qualifiers, or substi-
tuted one keyword for another in specifying the qualifiers. Specify the largest
unit first, and the smallest last.

-4632 Description of Error: Parenthetical precision of FRACTION must be between

1 and 5. No precision can be specified for other time units.
Corrective Action: You either specified an out-of-range precision for the
FRACTION field, or else you attempted to specify non-default precision for a
DATETIME field 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 qualifier from among the keywords
listed in the error message for whatever keyword you invented or mis-
spelled. 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 identifier of the SQL object.
You may be in the wrong database.

116 Error Messages

-4635 Description of Error: Cannot create temporary file filename to contain a blob
variable.
Corrective Action: An I/O error occurred while trying to write the tempo-
rary file in which the TEXT or BYTE variable is stored. This can be caused by
insufficient space on the disk, or by file 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 specified 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 prefix it with the table identifier, if other columns in the same data-
base 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 field in the INTERVAL qualifier 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 fields, or
DAY and larger fields, in the precision of an INTERVAL value.

-4644 Description of Error: The HELP and ATTRIBUTE clauses each can be speci-
fied 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 specified 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 report’s right margin.
Corrective Action: Modify your report routine so that the RIGHT MARGIN
specification is a column between the current column and the report margin,
and recompile.

-4647 Description of Error: Cannot open file filename to read a TEXT variable value.
Corrective Action: An I/O error occurred while trying to read the tempo-
rary file in which the TEXT or BYTE variable is stored. This can be caused by
insufficient space on the disk, or by file 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 key-
word with Character, Text, and Byte data. You can only use it with date and
number data.

1203 Description of Error: Cannot find message file. Check INFORMIXDIR and
DBLANG.
Corrective Action: INFORMIX-4GL cannot locate a needed message file.
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 files. 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-num-

ber.
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
specification file is not found in the database specified in the DATABASE sec-
tion. 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 specification file.

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 specification.

2012 Description of Error: Form output table form-name could not be opened.
Corrective Action: You may have exceeded the open file limit of 14 data files
(this number includes the output file). Reduce the number of tables included
in the form. Recompile the form specification.

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 fields, 260 two-
character fields, and 1000 fields of three characters or more. Reduce the num-
ber of tables in the default form. Recompile the form specification.

2018 Description of Error: The default form has exceeded its limit of 260 two-
character labels.
Corrective Action: The total number of two-character fields 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 fields. Recompile
the form specification.

2019 Description of Error: The default form has exceeded its limit of 26 one-char-
acter labels.
Corrective Action: The total number of one-character fields 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 fields. Recompile the form
specification.

2020 Description of Error: The following tables are involved: table-name.

Corrective Action: The indicated tables are involved in the specified
error(s).

2028 Description of Error: The form compilation found warnings and no errors.
Corrective Action: You can use the form, but check the specified file to check
the warnings.

4150 Description of Error: Program error at module-name, line number line-num-

ber.
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.

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
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

Index

AFTER DELETE clause

A INPUT ARRAY 7-133
a command-line option 1-62 AFTER FIELD clause
A symbol in PICTURE format INPUT ARRAY statement 7-132
strings 4-38 AFTER GROUP OF control
ABSOLUTE keyword, FETCH block 2-48, 5-25
statement 3-17, 7-98 AFTER keyword
Accept key 7-166 INPUT ARRAY statement 7-130
ACCEPT KEY keywords, OPTIONS INPUT statement 7-123
statement 7-79, 7-166 REPORT statement 5-25
Access privileges 3-41 Aggregate function
ALL 7-115, 7-187 AVG 5-46, 7-249
ALTER 7-16, 7-115, 7-187 COUNT 5-46, 7-249
CONNECT 3-41, 7-52, 7-116, GROUP 5-46, 7-223
7-187, E-23 in a query 5-46, 7-223, 7-240, 7-249
database privileges 7-42, 7-116 in a report 2-47, 5-26, 5-44
DBA 3-41, 7-116, 7-187 MAX 5-46, 7-249
default 3-41 MIN 5-46, 7-249
DELETE 7-115, 7-187 PERCENT 5-46
for a synonym 7-47 SUM 5-46, 7-249
for database administrator 3-41 with ALL 7-249
FROM PUBLIC 7-188 with DISTINCT or
INDEX 7-115, 7-187 UNIQUE 7-250
INSERT 7-115, 7-187, E-14 with NULL values 3-55, 5-46,
removing 7-187 7-250
RESOURCE 3-41, 7-116, 7-187 Alias of a table
SELECT 7-115, 7-187, 7-204 in a form specification file 4-14,
table privileges 3-41, 7-115 4-60, 7-35
TO PUBLIC 3-41, 7-116 in a SELECT statement 7-226,
UNIX permissions 7-42 7-235
UPDATE 7-115, 7-187 ALL keyword
view privileges 3-60, 7-117 aggregate functions 7-249
ACTION Menu (upscol dbschema utility E-22
utility) E-38 GRANT statement 7-115
Active set of a query 2-22, 3-14 REVOKE statement 7-187
ADD keyword, ALTER TABLE SELECT statement 7-222, 7-237
statement 7-14 with UNION operator 7-246
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

ALTER INDEX statement 3-12, arr_count function 6-6 ATTRIBUTE keyword

7-12 examples 7-135 CONSTRUCT statement 7-32
ALTER keyword arr_curr function 6-7 DISPLAY ARRAY
GRANT statement 7-115 examples 7-135 statement 4-59, 7-79
REVOKE statement 7-187 AS keyword DISPLAY FORM statement 7-83
ALTER TABLE statement 7-14 CREATE VIEW statement 7-57 DISPLAY statement 4-59, 7-75
Ampersand (&) symbol 2-44 GRANT statement 7-116, E-23 ERROR statement 7-92
AND keyword ASC keyword INPUT ARRAY statement 7-135
Boolean operator 2-13, 3-55 CREATE INDEX statement 7-44 INPUT statement 7-123, 7-129
COLOR attribute 4-25 ORDER BY clause 3-56, 7-243 MESSAGE statement 7-154
WHERE clause 7-234 ASCII characters OPEN WINDOW
with BETWEEN 4-25, 7-230 collating sequence 4-35, H-2 statement 7-160
Angle ( < ) brackets 4-42 from integer codes 2-25, H-2 OPTIONS statement 7-168
ansi ASCII files PROMPT statement 7-173
option of c4gl command 1-33, 7-7 colornames I-18 Attribute types
option of fglpc command 1-62, form specifications 4-3 AUTONEXT 4-23, 4-57
7-7 input data 7-143, E-11 BLINK 4-26, 4-59, 7-77, I-9, I-27
warning message 3-6, 7-7, 7-65 output from UNLOAD 7-144, BOLD 4-59, 7-163, I-27
ANSI standards for SQL 7-203 BORDER 7-163, I-6, I-24
compatibility with 7-7 .4gl source files 1-27, 1-56 COLOR 4-25, 4-63, E-40
ANY keyword, SELECT ASCII function 2-25 COMMENTS 4-27, 4-57
statement 7-237 Assignment statements 7-5 DEFAULT 4-19, 4-29, 4-57, 7-121,
Application program, attributes of display fields 4-16 E-39
compiling 1-27, 1-32, 1-56, 1-61, INITIALIZE 2-17, 7-120 DIM 4-59, 7-77, 7-163, I-27
7-7 LET 2-17, 7-142 DISPLAY LIKE 4-15, 4-31
Arguments Asterisk (*) notation DOWNSHIFT 4-32, E-39
for 4GL program command arithmetic operator 2-11, 7-219 FORMAT 4-33, E-41
line 6-5, 6-17 for all columns 2-15, 7-36 INCLUDE 4-19, 4-35, 4-57, 7-212,
for a 4GL function 7-19, 7-110 for all fields 4-54, 7-36 E-39
for a 4GL report 5-6 for record elements 2-15, 4-55, INVISIBLE 4-59, 7-77, 7-163, I-27
passed to a C function 2-55, 7-19, 7-111 LEFT 4-26, E-41
F-1 in a REPORT routine 5-6 NOENTRY 4-37
arg_val function 6-4 in a SELECT clause 7-222 NORMAL 4-59, 7-154, 7-163
Arithmetic operators in a USING format string 2-44 PICTURE 4-38, 4-57
in a SELECT clause 7-219, J-9 screen field overflow 2-46, 4-11, REQUIRED 4-40
in expressions 2-11, 2-36, 4-25 7-76 REVERSE 4-26, 4-42, 4-59, 7-163,
Array searching for * 7-33, 7-233 I-4, I-9, I-27
displaying 7-79, 7-192 wildcard 7-34, 7-232 SHIFT 4-57, E-39
of records 4-55, 6-7 with the COUNT keyword 3-55, UNDERLINE 4-26, 4-59, I-9, I-27
program array 2-10, 6-6, 7-71, 5-46, 7-249 UPSHIFT 4-43, E-39
7-79 with the PERCENT keyword 5-46 VALIDATE LIKE 4-15, 4-45
screen array 4-55, 7-79, 7-192 AT keyword VERIFY 4-46, 4-57
ARRAY data type 2-10, 5-8, 7-79 DISPLAY statement 7-75 WORDWRAP 4-21, 4-47
ARRAY keyword OPEN WINDOW ATTRIBUTES section of form
DEFINE statement 7-71 statement 7-160 specification
DISPLAY ARRAY statement 7-79 At ( @ ) sign 2-14, 3-7, 7-223 assigning attributes 4-16
INPUT ARRAY statement 7-129 assigning field names 4-16
Arrow keys I-4 default values 4-56, 7-168, E-39
definition of 4-16

2 Index
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

field tags 4-17, 4-25 BETWEEN keyword 3-65, 4-25, to specify array elements 2-10
fields linked to columns 4-15, 4-58, 7-229 to specify substrings 2-12, 4-18
4-17 Binding to database and Built-in functions 2-24, 5-44
for a multiple table form 4-6 forms 2-14, 4-17 BY keyword
for multiple-column fields 4-21 BLACK attribute 4-26, 4-59, 7-77, CONSTRUCT statement 7-32
for multiple-line fields 4-20 I-19 FORM4GL form specification
format 4-16, 4-22 Blank characters file 4-8
form-only fields 4-16, 4-18 DAY and HOUR separator 2-6, GROUP BY clause 7-240
input and display 4-22, 7-167 J-5, J-8 INPUT statement 2-14
table of attributes 4-22, 4-26 default character value 4-7, 4-29 ORDER BY clause 3-18, 7-243
AUDIT keyword in input files 7-144, E-12 REPORT statement 5-18, 7-184
CREATE AUDIT statement 3-46, in WORDWRAP fields 4-48 SCROLL statement 7-192
7-39 with CLIPPED operator 2-27 BY NAME keywords
DROP AUDIT statement 3-46, with FORMAT attribute 4-33 CONSTRUCT statement 7-32
7-85 with SPACE or SPACES 5-50 DISPLAY statement 7-75
Audit trails 3-45 BLINK attribute 4-26, 4-59, I-9, I-27 INPUT statement 2-14, 7-122
compared to transactions 3-45 BLOB data Intro-7 BYTE data type Intro-7
CREATE AUDIT 3-45, 7-39 BLUE attribute 4-26, 4-59, 7-77, I-19 B+ trees E-3
DROP AUDIT 3-45, 7-85 BOLD attribute 4-59, 7-77, I-27
RECOVER TABLE 3-46, 7-179 Boolean capabilities I-3, I-21
AUTOINDEX PATH access Boolean expression 2-13 C
method 7-194 examples 4-58, 7-230
C Compiler version of 4GL Intro-3,
Auto-indexing 3-52 in syscolatt 4-58, E-41
1-5, 1-7
AUTONEXT attribute 4-23, 4-57, with CASE 7-22
C compiler, function 1-32
E-39 with COLOR attribute 4-25, 4-63
C functions 1-66, 2-55, 7-19
AVG aggregate function 5-46, with CONSTRUCT 7-33
C language functions in 4GL
7-249 with IF 7-118
programs 1-32, 1-64, 2-55
with NULL values 3-55, 4-25
C shell C-2
with WHERE 7-218, 7-228
c4gl command 1-6, 1-32, 7-7
B with WHILE 7-216
CALL keyword, WHENEVER
Bordered window
Backup copy of a database 3-45, statement 7-213
graphics characters used 4-13,
3-46 CALL statement 2-18
7-163, I-24
bcheck utility E-2 passing parameters with 7-111
how displayed on screen 7-163
BEFORE FIELD clause RETURNING clause 2-56, 7-19
position on screen 7-160
INPUT ARRAY statement 7-132 syntax and notes 7-19
BOTTOM MARGIN
BEFORE GROUP OF control block with C functions 1-70, 2-58, 7-19
statement 5-16, 5-36
definition of 5-27 with library functions 6-3
Bourne shell C-2
guidelines for using 5-27 Calling convention for C
Braces ( { } ) symbols
BEFORE keyword functions 2-55
comment indicator 2-3, E-15
ALTER TABLE statement 7-14 CASE statement 2-19
page layout of form
INPUT ARRAY statement 7-130 EXIT CASE 7-96
specification 4-9
INPUT statement 7-123 syntax and notes 7-21
syntax convention Intro-10
REPORT statement 5-27 cat utility 1-64, 3-45
Brackets ( [ ] ) symbols
BEGIN WORK statement cfglgo command 1-66, 1-69
page layout of form
explicit transactions 3-44 CHAR data type
specification 4-9
syntax and notes 7-18 acceptable values 3-8, 7-50
pattern matching 7-233
Bell of a terminal, ringing 2-19, CHARACTER synonym 2-8, 3-8
syntax convention Intro-9
2-25, 4-38, 7-92 subscripts 4-18, 4-19, 7-220

Index 3
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

with database columns 3-8, 7-50 Column to compile a screen form 4-9, 4-62
with display fields 4-38, 4-47 adding 7-14 to create a customized
with variables 2-8, 7-71 changing column values 3-17, runner 1-69, 1-71
CHAR keyword, PROMPT 7-206 to invoke a 4GL program 1-6,
statement 7-173 changing data type 7-14 1-31, 1-64, 1-65, 1-72, 6-5, 6-17
CHARACTER data type 2-8, 3-8 constraints 7-16, 7-53 to invoke compiler 1-6, 1-32, 1-61
Character position 2-8, 4-18, E-13 designated as NOT NULL 7-51 Comment indicators 2-3, 4-10, I-3,
C-ISAM (indexed sequential access determining length 7-52 I-21
method) Intro-4, 3-50 indexed 3-50, 7-44 Comment line 7-162, E-39
CLEAR statement 2-19 joining 7-234, G-1 COMMENT LINE keywords
syntax and notes 7-23 naming conventions 3-6, 7-51 OPEN WINDOW
WINDOW 7-60 NULL value in 3-54 statement 7-161
CLIPPED keyword 2-12 removing 7-14 OPTIONS statement 7-165
in a string expression 2-38, 5-40 renaming 7-181 COMMENTS attribute 4-27, 4-57,
syntax and notes 2-27 virtual 3-59, 7-58 7-35, E-39
with DISPLAY 7-76 Column data types COMMIT WORK statement 3-42
CLOSE DATABASE statement CHAR 2-8, 7-50 ending transactions 3-23, 3-44
definition of 3-11 DATE 2-9, 7-51, C-3 syntax and notes 7-31
syntax and notes 7-27 DATETIME 2-9, 7-52, J-1 COMPILE Menu 1-27, 1-56
CLOSE FORM statement DECIMAL 2-7, 7-50, F-1 Compile option
closing an opened form 2-20, FLOAT 2-8, 7-50 FORM Menu 1-17, 1-47, 4-61
7-159 INTEGER 2-7, 7-50 MODULE Menu 1-12, 1-41
syntax and notes 7-28 INTERVAL 2-9, 7-52, J-1 PROGRAM Menu 1-22, 1-51
CLOSE statement MONEY 2-8, 7-50, C-5 Compile-time errors 1-11, 1-40,
and the FREE statement 7-109 SERIAL 7-51, 7-139 4-61, 7-7
and the SQLCA record 3-28 SMALLFLOAT 2-8, 7-50 Compiling
syntax and notes 7-25 SMALLINT 2-7, 7-50 command line 1-31, 1-32, 1-61
with a SELECT cursor 3-17, 7-25 COLUMN keyword 2-29, 7-181 help messages E-27
with an INSERT cursor 3-26, 7-25 Columns in Programmers
CLOSE WINDOW statement 2-20 in stores database tables A-2 Environment 1-10, 1-31, 1-39,
syntax and notes 7-30 in system catalogs B-1 1-61
CLUSTER keyword in upscol tables 4-56, E-37 programs that call C
ALTER INDEX statement 3-53, COLUMNS keyword, OPEN functions 1-65
7-12 WINDOW statement 7-160 screen forms 1-15, 1-45, 4-60
CREATE INDEX statement 3-53, Comma ( , ) symbol with ansi flag 1-32, 1-62, 3-6, 7-7
7-44 concatenation operator 2-12, Composite column list 7-16, 7-53
Colon ( : ) symbol 7-172 COMPRESS keyword,
as statement label prefix 7-213 in USING format strings 2-44 WORDWRAP attribute 4-48
delimiter in DATETIME separator in lists 2-15, I-21 Concatenation operator 2-12, 7-172
values 2-6, 7-34, E-12, J-5, J-8 COMMAND clause Concurrency control 3-42, 7-99
delimiter in INTERVAL MENU statement 7-149 Conditional statements
values 2-6, 7-34, E-12 Command file CASE 2-19, 7-21
field specification separator E-14, dbexport E-7 COLOR attribute 4-25, 4-63
I-4 dbload E-12 IF 2-19, 3-22, 7-118
LABEL statement 7-141 dbschema E-22 syscolatt file 4-58, E-41
ranges with CONSTRUCT 7-34 Command line WHILE 7-216
WHENEVER statement 7-213 arguments of a 4GL program 6-5, CONNECT access privilege 3-41,
COLOR attribute 4-25, 4-63, I-19 6-17 7-116, E-22
colornames file 4-59, E-40, I-9, I-18 to compile a message file E-28

4 Index
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

CONNECT keyword CREATE SYNONYM Cursor 3-13

GRANT statement 7-116 statement 3-11, 7-47 advancing 3-17, 7-98
REVOKE statement 7-187 CREATE TABLE statement 3-11 closing 3-18, 7-25
Constant assigning data types J-3 declaring 3-14, 7-64
date-time 2-12, J-1 guidelines for using 7-49 FOR UPDATE 3-17, 7-99, 7-157
floating number 2-5 NOT NULL clause 3-54, 7-51 non-SCROLLing 3-14
integer 2-5 notes 7-51 opening 3-17, 7-156
string 2-5 owner naming 7-51 position 3-19, 3-20
CONSTRAINT keyword syntax 7-49 scope of reference 2-5, 3-15, 7-67
ALTER TABLE statement 7-14 TEMP keyword 3-58, 7-51 SCROLL 3-14, 7-65
CREATE TABLE statement 7-49 UNIQUE keyword 7-53 with CLOSE 3-16, 7-25
Constraints 7-139 WITH NO LOG 7-50 with DELETE 3-18
changing 3-11, 7-16 CREATE VIEW statement 3-58 with FETCH 3-16, 7-99
creating 3-11, 7-53 guidelines for using 7-57 with FOREACH 3-16
names 3-7, 7-16, 7-53 owner naming 7-57 with FREE 3-40, 7-109
owner 3-7, 7-16 syntax and notes 7-57 WITH HOLD 3-14, 3-25, 7-26,
CONSTRUCT statement 2-20 WITH CHECK OPTION 3-60, 7-65, 7-157
NOENTRY fields 4-37 7-58 with INSERT 3-25, 7-9, 7-26, 7-65
symbols recognized 7-33 Currency symbol with OPEN 3-16, 7-156
syntax and notes 7-32 default ( = $ ) 2-8, 4-29, C-5 with SELECT 3-13, 7-64, 7-220
wildcard characters 7-34 in dbload input files E-12 with UPDATE 3-17, 7-99, 7-207
CONTINUE keyword, in format strings 2-47 CURSOR keyword
WHENEVER statement 2-21, Current database 3-11 DECLARE statement 3-14
2-22, 7-213 CLOSE DATABASE Cursor movement I-22
CONTINUE statement 2-19 statement 7-27 as determined by FETCH 3-17
FOR 7-105 closing 3-11, 7-27 as determined by INPUT 7-125
FOREACH 7-107 creating 3-11, 7-41 in a menu 7-150
MENU 7-152 DATABASE statement 7-62 in a screen array 7-80
syntax and notes 7-38 FETCH statement 7-99 in a screen form 4-23, 7-35
WHILE 7-216 selecting 3-11, 7-62 in a screen record 4-16
Control blocks 5-23 CURRENT function 3-65, 7-258 Cursor WITH HOLD
COUNT aggregate function 3-55, CURRENT keyword BEGIN WORK statement 3-25
5-46, 7-249 CURRENT function 2-30, 3-65 COMMIT WORK statement 3-25
CPU cost for a query 3-63, 7-194 DEFAULT attribute 4-30 DECLARE statement 3-24, 7-65
CREATE AUDIT statement 3-45, DELETE statement 3-18, 7-73 FETCH statement 3-24
7-39 FETCH statement 7-98 OPEN statement 7-157
CREATE DATABASE for a DATETIME value J-13 customer table in stores
statement 3-11 UPDATE statement 3-19, 7-207 database Intro-11, A-2
current database 7-41 CURRENT OF keywords Customized runners 1-50, 1-66
syntax and notes 7-41 DELETE statement 3-18, 7-73 CYAN attribute 4-26, 4-59, 7-77,
system catalogs 7-41 UPDATE statement 3-19, 7-207 I-19
WITH LOG IN 3-43, 7-42 Current option of a menu 1-8, 1-37
CREATE INDEX statement 3-12 Current row of a query 3-14, 3-18
syntax and notes 7-44 Current window 7-23, 7-60, 7-161 D
with ASC 7-16, 7-44, 7-53 CURRENT WINDOW Data access statements 7-6
with DESC 7-44 statement 2-20 GRANT 3-40
with UNIQUE and syntax and notes 7-60 LOCK TABLE 3-40
DISTINCT 7-44 REVOKE 3-40
UNLOCK TABLE 3-40

Index 5
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

Data conversion CHARACTER 2-8, 3-8 removing 3-11, 7-86

in an INSERT statement 7-140 DATE 2-9, 3-9, 4-29, 5-40, 7-51, removing indexes 3-12, 7-88
in an UPDATE statement 7-208 C-3, E-12, J-10 removing tables 3-11, 7-90
in expressions 2-10, 2-36 DATETIME 2-9, 3-10, 4-30, 5-40, renaming tables 3-11, 7-182
Data definition statements 7-6 E-12, J-2 replication with dbschema E-22
ALTER INDEX 3-12 DEC 2-8, 3-9 revoking user access 3-41, 7-187
ALTER TABLE 3-11 DECIMAL 2-7, 2-10, 3-9, 4-33, stores demonstration A-1
CLOSE DATABASE 3-11 7-50, F-1 system catalogs 3-5, B-1
CREATE DATABASE 3-11 DOUBLE PRECISION 2-8, 3-9 tables in 3-5, 7-49
CREATE INDEX 3-12 FLOAT 2-8, 3-9, 4-33 with a transaction log 3-42
CREATE SYNONYM 3-11 INT 2-7, 3-8 Database administrator (DBA)
CREATE TABLE 3-11 INTEGER 2-7, 3-8, 7-50 access privileges 1-18, 3-41,
CREATE VIEW 3-11 INTERVAL 2-9, 3-10, 4-30, 5-40, 7-116
DATABASE 3-11 E-12, J-5 Database conversion
DROP DATABASE 3-11 LIKE specification 2-9, 5-7 with dbupdate utility E-25
DROP INDEX 3-12 MONEY 2-8, 3-9, 4-29, 5-40, 7-50, with sqlconv utility E-31
DROP SYNONYM 3-12 C-5, E-12 Database engines Intro-6
DROP TABLE 3-11 NUMERIC 2-8, 3-9 DATABASE section of form
DROP VIEW 3-11 REAL 2-8, 3-9 specification
RENAME COLUMN 3-12 RECORD 2-9, 5-7 creating as FORMONLY 4-7
RENAME TABLE 3-11 SERIAL 2-9, 3-9, 4-37, 5-40, 7-51, definition of 4-7
UPDATE STATISTICS 3-12 7-139 format 4-6
Data fields E-12 SMALLFLOAT 2-8, 3-9 WITHOUT NULL INPUT 4-7,
Data integrity statements 3-42, 7-6 SMALLINT 2-7, 3-8 4-29
Data manipulation statements 7-6 TEXT Intro-7 DATABASE statement 2-22
DELETE 3-12, 7-73 VARCHAR Intro-7 definition of 3-11, 7-62
INSERT 3-12, 7-138 Data validation EXCLUSIVE 7-63
LOAD 3-12, 7-143 upscol utility 4-56, E-39 syntax and notes 7-62
SELECT 3-12, 7-193, 7-218 using views 3-60 DATE data type
UNLOAD 3-12, 7-203 VALIDATE LIKE attribute 4-45 acceptable values 2-46, 7-51
UPDATE 3-12, 7-206 VALIDATE statement 2-24, 7-211 data conversion J-16
Data type Database in dbload input files E-12
binary large objects access privileges 3-41 manipulating arithmetically J-10
(BLOB) Intro-7 closing 7-27 with database columns 3-9
C language 2-55, F-2 creating 3-64, 7-41 with display fields 2-46, 2-47,
changing 7-14 creating tables 3-11, 7-49 4-29, 4-33, 7-52, C-3
conversion 2-10, 2-36, 7-140 creating views 3-58, 7-57 with variables 2-9, 7-71
date-time data types J-1 data manipulation DATE keyword
floating decimal point 2-8, 3-9 statements 3-12 CREATE TABLE statement 7-51
of columns in a table 3-8, 7-49 database subdirectory 3-5, 7-41 DATE function 2-32
of variables 5-7, 7-71, 7-120 granting user access 3-41, 7-115 DATE() function 2-33, 7-9, 7-252
of view columns 7-58 indexes 3-50 DATETIME data type 2-9, J-2
storage requirements 7-52 map of stores A-5 acceptable values 7-51, J-2
synonyms 2-7 naming conventions 3-6, 7-41 entered as a character string J-8
Data types owner naming and MODE entered as a literal value 4-30, J-3
ARRAY 2-10, 5-8 ANSI 3-7 in dbload input files E-12
BYTE Intro-7 recovering Intro-7, 3-45 manipulating arithmetically 2-36,
CHAR 2-8, 3-8, 4-29, 5-40, 7-50, relational 3-5 J-9
E-14 remote 7-35

6 Index
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

using the CURRENT DECIMAL data type defining variables 2-4, 2-7, 7-71
keyword J-13 acceptable values 2-7, 3-9, 7-50 in a function 2-4, 7-110
with database columns 3-10 DEC synonym 2-8, 3-9 in a report 2-4, 5-7, 7-184
with display fields 4-30 floating decimal point in 2-7, LIKE keyword 2-9, 7-71
with variables 2-9, 7-71, J-16 2-44, 3-9 location 2-4
Date-time expression 2-12, 7-248 NUMERIC synonym 2-8, 3-9 scope of variables 2-17
DAY keyword scale and precision 2-7, 2-10, 2-11 syntax and notes 7-71
DATETIME qualifier 3-10, J-2 with database columns 3-9 Defining global variables 2-4, 7-112
DAY( ) function 2-34, 7-9, 7-253 with display fields 2-44, 4-33 Delete key 7-166, I-5, I-23
INTERVAL qualifier 3-10, J-12 with variables 2-7, 7-71, F-1 DELETE keyword
DBA access privilege 3-7, 3-41, DECIMAL functions for C F-1 GRANT statement 7-115
7-16, 7-85, E-6, E-23 DECLARE statement INPUT ARRAY statement 7-130
DBA keyword and SQLCA record 3-63 OPTIONS statement 7-166
GRANT statement 7-116 assigning a cursor 3-14, 3-29 REVOKE statement 7-187
REVOKE statement 7-187 DELETE operations 3-25 DELETE statement 3-12
DBA (Database FOR UPDATE 3-19, 7-66, 7-74 DATETIME or INTERVAL
Administrator) 3-40, 3-45 guidelines for using 3-35 values J-15
DBANSIWARN environment INSERT cursor 3-26, 3-37, 7-139 examples 3-33
variable 3-6, 3-25, 3-64, 7-7, C-2 SCROLL option 3-20, 7-65 functions in 7-248
DBDATE environment SELECT cursor 3-14, 3-35 syntax and notes 7-73
variable C-3 syntax and notes 7-64 WHERE CURRENT OF
DBDELIMITER environment WITH HOLD option 3-23, 7-65 clause 3-18, 3-19
variable 7-144, 7-203, C-3, E-12 DEFAULT attribute 4-29, 4-57 DELIMITER keyword
DBEDIT environment CURRENT 4-30 dbload command file E-12
variable 1-12, 1-26, 1-41, 1-55, TODAY 4-30 LOAD statement 7-143
C-4 with INITIALIZE statement 4-58, UNLOAD statement 7-203
dbexport utility E-6 7-121 Delimiters in a screen form 4-11
DBLANG environment with WITHOUT changing 4-52
variable C-4, E-30 DEFAULTS 4-29, 7-124 DELIMITERS statement 4-52
dbload utility E-11, E-33 with WITHOUT NULL Demonstration application,
DBMONEY environment INPUT 4-29 listing A-15
variable C-5 Default editor 1-26, 1-55, C-4 Demonstration database A-1
DBPATH environment Default form specification file description of Intro-11, A-1
variable 1-18, 1-29, 1-58, C-6, creating at system prompt 4-62 restoring 1-6
E-23 generating 1-16, 1-46, 4-61 DESC keyword
DBPRINT environment modifying 1-16, 1-46, 4-61 CREATE INDEX statement 7-44
variable 5-10, C-6 Default screen attributes 4-56, ORDER BY clause 3-56, 7-243
dbschema utility E-22 7-168 DIM attribute 4-59, 7-77, I-8
DBTEMP environment Default screen record 4-55 Direct memory access
variable C-6 DEFER statement (DMA) Intro-4
dbupdate utility 3-54, E-25 forms of 2-23 DISPLAY ARRAY statement 2-20
Deadlock 7-197 global flags set 2-23, 7-69 arr_curr function 6-7
Debug option INTERRUPT 2-23 EXIT DISPLAY 7-96
MODULE Menu 1-42 syntax and notes 7-69 set_count function 6-20
PROGRAM Menu 1-53 DEFINE statement syntax and notes 7-79
Debugger, Interactive Intro-4, 1-38, defining a program array 2-10 DISPLAY ATTRIBUTE
1-53, 1-65 defining a record 2-9, 7-72 keywords 7-168
Debugger, invoking 1-59, 1-61 defining global variables 2-4,
DEC data type 2-8, 3-9 7-112

Index 7
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

Display field 4-10 DROP keyword, ALTER TABLE DBEDIT 1-12, 1-15, 1-26, 1-41,
default field widths 4-11 statement 7-14 1-45, 1-55, 4-61, C-4
determining field widths 4-11 Drop option, PROGRAM DBLANG C-4, E-30
dividing long CHAR Menu 1-24 DBMONEY C-5
columns 4-18, 4-19 DROP SYNONYM statement 3-12, DBPATH 1-18, 1-29, 1-58, 7-62,
field names 4-11, 4-16, 4-22 7-89 C-6
field tag 4-10, 4-25, 4-63 DROP TABLE statement 3-11 DBPRINT 5-10, C-6
format of 2-44, 4-10 syntax and notes 7-90 DBTEMP C-6
form-only field 4-16, 4-18 DROP VIEW statement 3-58 INFORMIXDIR C-7, E-30
guidelines for using 4-11 syntax and notes 7-91 INFORMIXTERM C-7, I-1, I-20
labels for 4-12 Dynamic management SQLEXEC C-7
multiple-column 4-21, 4-34, 4-42 statements 7-6 TERMINFO I-20, I-25
multiple-line fields 4-11, 4-47 DECLARE 3-29 Equal ( = ) sign 2-13, 4-16, 7-33
screen arrays 4-11, 4-54, 7-79 EXECUTE 3-28 Error handling
specifying search criteria 7-32 FREE 3-29 4GL library functions 6-10
verifying field widths 4-12 PREPARE 3-28 built-in functions 2-22
DISPLAY FORM statement 2-20 compile-time errors 1-11, 1-40,
syntax and notes 7-83 4-63
DISPLAY LIKE attribute 4-15, 4-31 E creating an error log 6-23
DISPLAY statement 2-20 displaying error messages 6-11,
EBCDIC conversion of ASCII
AT 2-27 7-92
strings 2-58
BY NAME 7-76 errorlog function 6-13
Editor blanks (in multiple-line
CLIPPED 2-27 exception handling 2-23, 7-69
fields) 4-48
EXIT DISPLAY 7-96 Interrupt key 2-21, 7-69
Ellipsis ( . . . ) symbols 7-150
formatting 2-46 logging programmer-defined
syntax convention Intro-11
syntax and notes 7-75 error messages 6-13
ELSE keyword, IF statement 7-118
TO 2-15 overview of 2-21
END keyword
DISTINCT keyword run-time errors 1-65, 2-21, 6-23
CASE statement 2-19, 7-21
aggregate functions 3-55, 7-249 SQLCA global record 2-22, 3-63
DEFINE statement 7-71
ALTER TABLE statement 7-16 startlog function 6-23
DISPLAY ARRAY statement 7-79
CREATE INDEX statement 7-44 trapping errors 2-22, 7-214
FOR statement 7-104
CREATE TABLE statement 7-53 trapping interrupts 2-23, 7-69
FOREACH statement 7-106
SELECT statement 7-222 trapping warnings 2-22, 7-213
FORM4GL form specification
Distributed query across WHENEVER statement 2-22
file 4-10
databases Intro-7 with status variable 2-22, 6-10
FUNCTION statement 7-110
Documentation Intro-3 ERROR keyword
GLOBALS statement 7-112
DOUBLE PRECISION data ERROR statement 7-92
IF statement 7-118
type 2-8, 3-9 OPTIONS statement 7-165
INPUT ARRAY statement 7-130
DOWN keyword WHENEVER statement 7-213
MAIN program block 7-148
SCROLL statement 7-192 Error line
MENU statement 7-150
syscolval table 4-57, E-39 err_print function 6-11
PROMPT statement 7-174
DOWNSHIFT attribute 4-32, 7-35, err_quit function 6-12
REPORT statement 5-20, 7-184
E-39 location 7-167
WHILE statement 3-27, 7-216
downshift function 6-9 Error log file 6-13, 6-23, E-11
Environment variable
DROP AUDIT statement 3-45, 7-85 Error messages 1-35, 6-10, 6-12,
DBANSIWARN 3-6, 3-64, 7-7, C-2
DROP DATABASE statement 3-11 6-23
DBDATE C-3
syntax and notes 7-86 editing the 4glusr.msg file E-29
DBDELIMITER 7-144, 7-203, C-3
DROP INDEX statement 3-12 Error record 6-23
syntax and notes 7-88 ERROR statement 2-19, 7-92

8 Index
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

errorlog function 2-23, 6-13 number 2-11, 2-44 .erc 1-35, 1-72
err_get function 2-23, 6-10 string 2-12 .err 1-31, 1-35, 1-60, 1-72, 4-12,
err_print function 2-23, 6-11 using in statements 2-13 4-63, 7-7
err_quit function 2-23, 6-12 EXTEND function 2-35, 7-260, J-11 .exp E-7
Escape key 7-167 EXTERNAL keyword .fbm 1-36, 1-73
ESCAPE keyword, WHERE REPORT statement 5-18, 7-184 .frm 1-35, 1-72, 4-61, 4-62, 4-63
clause 7-231, 7-232 .h 1-70, F-1
ESQL/C .idx 3-5, E-2
functions 1-32, 1-64 F .msg E-29
language Intro-4 .o 1-10, 1-27, 1-35
FALSE (Boolean constant) 2-5, 3-55
EVERY ROW keywords .out 1-33, 1-69, 7-194, E-6
FETCH statement
default FORMAT section of a .pbr 1-36, 1-73
default condition 7-99
report 5-20 .per 1-15, 1-35, 1-72, 4-63
examples 3-36
ON EVERY ROW control .sql E-7
guidelines for using 3-16
block 5-31 .src A-15
NOTFOUND code 3-63, 7-99
EXCLUSIVE keyword FILE keyword
syntax and notes 7-98
DATABASE statement 7-62 dbload command file E-12
with SELECT 3-36, 7-224
LOCK TABLE statement 3-49, OPTIONS statement 7-166, E-27
fgiusr.c file 1-67
7-146 Fill character
fgldb command 1-66
Exclusive mode, opening the ampersand 2-44
fglgo command 1-6, 1-50, 1-64, 6-4
database 3-45, 7-200, E-6 asterisks 2-44
fglpc command 1-6, 1-61, 7-7
EXECUTE statement 3-28 dollar sign 2-45
FIELD keyword
guidelines for using 3-33 parentheses 2-45
INPUT ARRAY statement 7-130
syntax and notes 7-94 pound sign 2-44, 4-33
INPUT statement 7-123
USING 3-33 table of 2-44
Field names in screen forms 4-15,
EXISTS keyword, SELECT Filters in a query 7-194, G-3
4-17, 6-14
statement 7-238 FINISH REPORT statement 2-21
Field tag 4-9
Exit option guidelines for using 5-33
generated by FORM4GL 4-11
FORM Menu 1-18, 1-47 syntax and notes 7-101
in Boolean expressions 4-25, 4-63
MODULE Menu 1-14, 1-43 FIRST keyword
in the ATTRIBUTES section 4-16
PROGRAM Menu 1-24, 1-53 FETCH statement 3-23, 7-98
in the SCREEN section 4-10, 4-11
EXIT statement 2-19 OPEN WINDOW
naming conventions 4-17
CASE 7-21 statement 7-161
Fields of input records 7-143, E-11
DISPLAY 7-79 OPTIONS statement 7-167
File extensions
FOR 7-105 REPORT statement 5-29
.4be 1-36, 1-73
FOREACH 7-107 FIRST PAGE HEADER control
.4bl 1-35, 1-73
INPUT ARRAY 7-130 block 5-29, 5-34
.4bo 1-35, 1-73
MENU 3-23, 7-150 Fixed-length records E-12
.4ge 1-10, 1-13, 1-20, 1-35, A-15
PROGRAM 7-97 FLOAT data type
.4gi 1-49, 1-54, 1-56, 1-58, 1-64,
syntax and notes 7-96 acceptable values 3-9, 7-50
1-72
WHILE 7-216 DOUBLE PRECISION
.4gl 1-11, 1-26, 1-32, 1-35, 1-54,
Expression 2-11 synonym 2-8, 3-9
1-55, 1-61, 1-72, A-15
Boolean 2-13, 3-55, 7-21 with database columns 3-9
.4go 1-50, 1-54, 1-56, 1-61, 1-62,
data conversion 2-10, J-11 with display fields 4-33
1-64, 1-72
date-time 2-12, 2-36, J-1, J-11 with variables 2-8, 7-71
.c 1-21, 1-35, 1-69
in a report 5-44 Floating number constant 2-5
.dat 3-5, E-2
in a SELECT statement 7-219
.dbs 3-5
NULL values 3-54
.ec 1-21, 1-29, 1-32, 1-35, 1-69

Index 9
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

FLUSH statement SCREEN 4-4, 4-8 LINENO 5-48

guidelines for using 3-26 TABLES 4-4, 4-14 NEED statement 5-38
status variable and SQLCA Form specification file, using 4-3 ON EVERY ROW 5-31
record 3-28 correcting errors 1-16 ON LAST ROW 5-33
syntax and notes 7-102 creating 4-62 PAGE HEADER 5-34
FOR keyword default form specification PAGE TRAILER 5-36
CONTINUE statement 7-38 file 4-62 PAGENO 5-49
CREATE AUDIT statement 3-46, generating 1-14, 1-43, 4-61 PAUSE statement 5-39
7-39 graphics characters 4-12 PRINT FILE statement 5-42
CREATE SYNONYM identifier 2-5, 7-28, 7-159 PRINT statement 5-40
statement 7-47 multiple tables in 4-14, 4-61 SKIP statement 5-43
DECLARE statement 3-25, 7-64 overview 4-3 SPACE 5-50
DROP AUDIT statement 7-85 PERFORM forms 4-63 TIME 2-41
PROMPT statement 7-173 structure 4-4 USING 5-40
UPDATE STATISTICS FORM4GL WORDWRAP 5-40, 5-51
statement 7-210 attribute syntax 4-22 Format strings
FOR statement 2-18 command line syntax 4-9, 4-62, with FORMAT attribute 4-33,
EXIT FOR 7-96 4-63 E-41
syntax and notes 7-104 creating a default form with PICTURE attribute 4-38
FOR UPDATE cursor specification file 4-61 with USING operator 2-44
DECLARE statement 3-17, 7-64 default display field 4-9 Formatting a report
DELETE statement 3-18 default field tags 4-62 automatic page numbering 5-35
FETCH statement 3-19, 7-99 default screen records 4-54 default report format 5-21
FOREACH statement 3-19 description 4-3 formatting dates 2-46, C-3
OPEN statement 3-48, 7-157 file extensions created by 4-63 formatting numbers 2-44
row-level locking 3-48 from Programmers grouping data 5-46
FOREACH statement 2-18 Environment 1-17, 1-46, 4-61 page headers and trailers 5-29,
CONTINUE FOREACH 7-38 graphics characters in screen 5-34, 5-36
examples 3-16 section 4-12 printing column headings 5-35
EXIT FOREACH 7-96 subscripting a CHAR setting margins 5-12, 5-13, 5-15,
syntax and notes 7-106 column 4-18 5-16
Foreground colors 7-168, I-17 using defaults in syscolval and setting page length 5-17
FORM Design Menu 1-14, 4-61 syscolatt 4-17 skipping to top of page 5-43
FORM keyword verifying field widths 4-12 starting on a new page 5-38
CLEAR statement 7-23 FORMAT attribute 4-33 Formatting number
CLOSE FORM statement 7-28 guidelines for using 4-33 expressions 2-44
OPEN FORM statement 7-159 multiple-column fields 4-21 Form-only field 4-18, 4-19, 4-22
OPEN WINDOW FORMAT section of REPORT FORMONLY keyword
statement 7-160 statement ATTRIBUTES section 4-18
OPTIONS statement 7-168 AFTER GROUP OF 5-25 DATABASE section 4-7, 4-15
FORM LINE keywords aggregate functions 5-46 INSTRUCTIONS section 4-54
OPEN WINDOW BEFORE GROUP OF 5-27 FRACTION keyword
statement 7-161 CLIPPED 5-40 DATETIME qualifier 3-10, J-2
OPTIONS statement 7-166 COLUMN 5-35 INTERVAL qualifier 3-10, J-6
Form specification file, sections of control blocks 5-23 FREE statement 3-29, 3-39, 7-109
ATTRIBUTES 4-4, 4-16, 7-167 definition of 5-20, 7-184 FROM clause
DATABASE 4-4, 4-7 EVERY ROW 5-13, 5-21 OUTER keyword 3-62, 7-226, G-3
INSTRUCTIONS 4-51 fill characters 2-44 SELECT statement 3-62, 7-226
FIRST PAGE HEADER 5-29 table alias 7-235

10 Index
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

FROM keyword
CONSTRUCT statement 7-32 G H
DELETE statement 7-73 Generate option, FORM HAVING clause, SELECT
INPUT ARRAY statement 7-129 Menu 1-16, 1-46 statement 7-242
INPUT statement 7-122 Global flags 2-23 HEADER keyword
LOAD statement 7-143 Global Source array 1-50 FIRST PAGE HEADER control
OPEN FORM statement 7-159 Global variables 2-4 block 5-29
PREPARE statement 3-30, 7-171 GLOBALS statement 2-18 PAGE HEADER control
PUT statement 7-177 syntax and notes 7-112 block 5-34
REVOKE statement 7-187 with DEFINE LIKE 7-112 Help file
SELECT statement 3-62 GO TO or GOTO keywords calling help messages 7-150,
Function WHENEVER statement 7-213 7-151, 7-166, 7-173
ASCII 2-25 GOTO statement compiling with mkmessage E-27
CLIPPED 2-27 LABEL 2-19, 7-114, 7-141 designating a Help key 7-166
COLUMN 2-29 syntax and notes 7-114 designating a pathname 7-166
CURRENT 3-65, 4-30, 7-258, J-13 GRANT statement 3-40, 7-10 format of E-27
DATE 2-32 CONNECT 3-41 showhelp function 6-21, E-29
DATE() 2-33, 7-252 DBA 3-41 HELP keyword
DAY() 2-34, 7-253 RESOURCE 3-41 INPUT ARRAY statement 7-129
EXTEND() 2-35, 7-9, 7-260 syntax and notes 7-115 INPUT statement 7-123
LENGTH() 2-38, 7-9 table privileges 3-41 MENU statement 7-149
MDY() 2-39, 7-254 Graphics characters in forms 4-12 OPTIONS statement 7-166, E-27
MONTH() 2-40, 7-9, 7-255 Greater ( > ) than symbol 1-64, 2-13, PROMPT statement 7-173
SPACES 5-50 E-19 Help line 7-149, 7-154
TIME 2-41 relational operator 2-13, 7-33 Help menu 6-21, E-29
TODAY 2-42, 3-65, 4-30, 7-9 REVERSE attribute 4-42 Help message
USER 3-65 GREEN attribute 4-26, 4-59, 7-77, creating and compiling 1-9, 1-38,
WEEKDAY( ) 2-53, 7-9, 7-256 I-19 E-27
WORDWRAP 5-51 GROUP aggregate functions 5-46 displaying 1-8, 1-37, 6-22, 7-123,
YEAR( ) 2-54, 7-9, 7-257 GROUP BY clause, SELECT 7-129, 7-166
Function keys 1-50, I-5, I-23 statement Hidden options of menus 7-152
FUNCTION statement in definition of a view 3-59 High availability Intro-7
and variables 2-17 syntax and notes 7-240 HOLD keyword, DECLARE
defining a record in 7-111 with NULL values 3-56 statement 7-64
parameters in 2-17, 7-110 GROUP keyword HOUR keyword
RETURN 7-110, 7-186 AFTER GROUP OF control DATETIME qualifier 3-10, J-2
syntax and notes 7-110 block 5-25 INTERVAL qualifier 3-10, J-6
Functions 2-17 BEFORE GROUP OF control Hyphen ( - ) symbol
4GL library 2-22, 6-3 block 5-27 comment indicator 2-4
aggregate 3-55, 7-249 REPORT statement 5-46 delimiter in DATETIME
built-in functions 2-24 values E-12
C language 1-32, 1-64, 2-55, F-1 delimiter in INTERVAL
calling a function 7-19, 7-111 values E-12
in an expression 6-3 in USING format strings 2-45
INFORMIX-ESQL/C 1-32, 1-64 in window border 4-13, I-6
values returned 2-17, 7-111 range indicator in dbload
files E-13

Index 11
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

INDEX PATH table access INPUT NO WRAP keywords

I method 7-194 OPTIONS statement 7-166
i4gl command 1-6, 1-25, 4-61 Indirect typing of program INPUT statement 2-20
i4gldemo script Intro-11, 1-6 variables 7-71 arr_count function 6-6
Identifier infield function EXIT INPUT 7-96
defining 3-28, 4-54, 7-71 help messages E-29 infield function 6-14, 7-126
distinction between INFORMIX- ON KEY 7-126 NOENTRY fields 4-37
4GL and SQL 3-7 syntax and notes 6-14, 7-134 syntax and notes 7-122
naming conventions 2-4, 4-54 infocmp utility I-24, I-27 terminating 7-125
PREPAREd statements 7-67, informix user name E-6 INSERT cursor
7-109 INFORMIX-4GL closing 3-26, 7-25
scope of reference 2-4, 7-67, 7-172 as a report writer 5-3 declaring 3-25, 3-37, 7-64
IF statement 2-19 as a screen-building utility 4-3 flushing the insert buffer 7-25,
relationship to CASE 7-22 command file names 1-31, 1-61 7-102
syntax and notes 7-118 language overview 2-3 guidelines for using 3-25
Implicit transactions 3-6 versions Intro-3, 1-5 opening 3-37, 7-156
IN keyword INFORMIXDIR environment putting a row in the insert
CREATE AUDIT statement 3-46, variable C-7, E-30 buffer 7-177
7-39 INFORMIX-ESQL/C Insert key 7-166, I-5, I-23
CREATE DATABASE functions 1-32, 1-64 INSERT keyword
statement 3-43 INFORMIX-OnLine database dbload command file E-12
CREATE TABLE statement 7-10, engine Intro-6, 7-6 DECLARE statement 3-26, 7-64
7-50 INFORMIX-SE database GRANT statement 7-115, E-14
LOCK TABLE statement 3-49, engine Intro-6, 7-6 INPUT ARRAY statement 7-130
7-146 INFORMIX-SQL application LOAD statement 7-143
SELECT statement 7-230 development tool 4-63 OPTIONS statement 7-166
START DATABASE INFORMIX-STAR add-on Intro-7 REVOKE statement 7-187
statement 3-43 INFORMIXTERM environment INSERT statement 3-12
INCLUDE attribute 4-57 variable C-7, I-1, I-20 DATETIME or INTERVAL
definition of 4-35 INITIALIZE statement 2-17, 7-120 values J-8
guidelines for using 4-35 INPUT ARRAY statement 2-20 functions in 7-248
specifying values in 7-212 arr_curr function 6-7 inserting through a view 3-59
Index infield function 6-14, 7-134 running a PREPAREd 3-37
ascending and descending 7-53 NOENTRY fields 4-37 SERIAL columns in 7-139
auto_indexing 3-52 scr_line function 6-18 syntax and notes 7-138
check and repair index files E-2 set_count function 6-20 with NULL values 3-57
clustered 3-52, 7-12, 7-45 syntax and notes 7-129 INSTRUCTIONS section of form
creating the index 7-44, E-22 table of functions in 7-135 specification
filters 3-52, 7-194 terminating 7-132 definition of 4-51
guidelines for using 3-50 INPUT ATTRIBUTE clause of DELIMITERS statement 4-52
multiple-column 7-16, 7-44 OPTIONS statement 7-168 screen arrays 4-55
NULL value 3-54 Input buffer 3-26, 7-139 SCREEN RECORD
removing from a database 7-88 Input files statement 4-54
UNIQUE 7-44, 7-53, 7-139 dbload utility E-11 screen records 4-54
with dbload utility E-20 LOAD statement 7-143 INT data type 2-7, 3-8
INDEX keyword INPUT keyword Integer constant 2-5
GRANT statement 7-115 INPUT statement 7-122 INTEGER data type
REVOKE statement 7-187 OPTIONS statement 7-166 acceptable values 2-7, 3-8, 7-50
INT synonym 2-7, 3-8

12 Index
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

with database columns 3-8 IS keyword 2-13, 3-56, 7-60, 7-234

with display fields 4-7 ISAM record number 3-62 L
with variables 2-7, 7-71 Italics, in syntax LABEL statement
Intentional blanks (in multiple-line statements Intro-10 GOTO 2-19, 7-114, 7-141, 7-213
fields) 4-48 items table in stores syntax and notes 7-141
Interactive Debugger database Intro-11, A-3 LAST keyword
Debugger path 1-50 FETCH statement 3-23, 7-98
description of Intro-4, 1-65 OPEN WINDOW statement
invoking 1-38, 1-53 J 7-161
Interactive mode OPTIONS statement 7-167
Joins 4-63, 7-234
bcheck utility E-3 REPORT statement 5-33
columns with the same
dbload utility E-18 LEFT attribute 4-26
name 7-235, G-1
Interrupt key 2-23, 7-69, E-20 LEFT MARGIN statement 5-12
in definition of a view 3-59
INTERRUPT keyword, DEFER LENGTH keyword
multiple joins 7-235, G-5
statement 2-23, 7-69 LENGTH( ) function 2-38, 6-16,
NULL column values 3-56, G-3
Interrupt signal 2-23, 7-69 7-251
outer join 3-61, 7-235, G-1
INTERVAL data type 2-9, J-5 PAGE LENGTH statement 5-17
self-join 7-235
acceptable values 7-51 Less ( < ) than symbol
stores database columns A-5
entered as a character string J-8 in USING format strings 2-44
entered as a literal value 4-30, J-6 relational operator 2-13, 7-33
in dbload input files E-12
manipulating arithmetically 2-36,
K REVERSE attribute 4-42
LET statement 2-17
J-9 Kernel locking 3-50, 7-197 CLIPPED 2-27, 3-31
using the UNITS keyword J-13 Key examples 2-38
with database columns 3-10 Accept key 7-34, 7-124, 7-166 syntax and notes 7-142
with display fields 4-30 arrow keys 7-35, 7-125 USING 2-46
with variables 2-9, 7-71 function keys 7-125, 7-133, 7-167 with string expressions 2-8
INTO keyword Help key 7-129, 7-166, E-27 Library functions (INFORMIX-
dbload command file E-13 Interrupt 2-23, 7-34, 7-152 4GL)
FETCH statement 3-17, 7-98 Quit 2-23, 7-69 arg_val 6-4
FOREACH statement 3-16 restricted 7-125 arr_count 6-6
INSERT statement 7-139 scrolling and editing 7-35, 7-166 arr_curr 6-7
LOAD statement 7-143 used in screen arrays 7-131, 7-166 downshift 6-9
SELECT statement 3-29, 7-224, KEY keyword errorlog 6-13
7-245 INPUT ARRAY statement 7-132 err_get 6-10
INTO TEMP clause INPUT statement 7-123 err_print 6-11
SELECT statement 7-8, 7-245 MENU statement 7-149 err_quit 6-12
with INSERT statement 7-139 OPTIONS statement 7-166 infield 6-14, 7-126, 7-134
int_flag variable 2-23, 7-69 Keywords, notation in syntax length 6-16, 7-251
Inverse video (synonym for statements Intro-10 num_args 6-17
reverse) 4-58 scr_line 6-18
INVISIBLE attribute 4-59, 7-77 set_count 6-20
Invoking showhelp 6-21
4GL Compiler 1-6, 1-32, 1-61 startlog 6-23
4GL programs 1-6, 1-30, 1-52 upshift 6-25
FORM4GL 1-17, 1-46, 4-63 LIFO (last-in, first-out) queue 2-55
Interactive Debugger 1-38, 1-59 LIKE data type specification 7-138
Programmers Environment 1-6,
1-7, 1-36

Index 13
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

LIKE keyword in 4GL statements 2-3, 4-11 Message numbers in help files E-27
DEFINE statement 2-10, 7-71 in syntax statements Intro-10 MESSAGE statement 2-19
DISPLAY LIKE attribute 4-31 SHIFT attribute 4-57, E-39 syntax and notes 7-154
FORMONLY fields 4-19 UPSHIFT attribute 4-43, E-39 MIN aggregate function 3-64, 5-46,
GLOBALS statement 7-112 upshift function 6-25 7-249
INITIALIZE statement 7-120 Minus ( - ) sign
RECORD data type 2-9 arithmetic operator 2-11, 4-25,
SELECT statement 2-13, 7-231 M 7-219
VALIDATE LIKE attribute 4-45 comment indicator 2-4
MAGENTA attribute 4-26, 4-59,
VALIDATE statement 2-24, 7-211 delimiter in DATETIME
I-19
WHERE clause 7-231 values 2-6, E-12
MAIN statement
LINE keyword delimiter in INTERVAL
description 2-17
OPEN WINDOW values 2-6, E-12
in source-code modules 1-33
statement 7-161 in USING format strings 2-45
syntax and notes 7-148
OPTIONS statement 7-165 in window border 4-13, I-6
manufact table in stores
SKIP statement 5-43 unary operator 2-5, 2-6, 4-25
database Intro-11, A-4
Line mode of a terminal 7-175 MINUTE keyword
MARGIN keyword
LINENO expression 5-48 DATETIME qualifier 3-10, J-2
BOTTOM MARGIN
LINES keyword INTERVAL qualifier 3-10, J-6
statement 5-16
NEED statement 5-38 mkmessage utility 1-9, 1-38, E-27
LEFT MARGIN statement 5-12
SKIP statement 5-43 MODE ANSI database
RIGHT MARGIN statement 5-13
LOAD statement 3-29, 7-143 comment indicators 2-4
TOP MARGIN statement 5-15
Local variables 2-4, 5-7 description of 3-6
WORDWRAP function 5-40
LOCK TABLE statement 3-40, 3-47 error handling 2-22
MATCHES keyword, in WHERE
syntax and notes 7-146 implicit transactions 3-6, 3-43
clause 4-58, 7-8, 7-33, 7-232
Locking owner naming 3-7, 4-15
MAX aggregate function 3-64, 5-46,
guidelines for using 3-47 specifying 3-42
7-249
row-level 3-48, 7-139, 7-146 syntax checking 3-6, 3-64, 7-7
MDY function 2-39, 7-254
table-level 3-49, 7-146, E-19 table access privileges 3-41
Menu options of Programmers
LOG keyword MODE ANSI keywords
Environment 1-7, 1-30
CREATE DATABASE CREATE DATABASE
MENU statement
statement 3-43 statement 3-43, 7-41
CONTINUE MENU 7-38
CREATE TABLE statement 7-50 START DATABASE
description 2-19
SELECT statement 7-245 statement 3-42, 7-200
EXIT MENU 7-96
START DATABASE MODE keyword
help messages 7-151
statement 3-43 CREATE DATABASE
syntax and notes 7-149
Logging statement 3-43
Menu-building utility 7-149
error messages 6-23, E-19 LOCK TABLE statement 7-146
Menu, programmer-defined
of temporary tables 7-50 SET LOCK MODE
creating 7-149
transactions 3-43 statement 3-48, 7-197
displaying options 7-38, 7-151
LOOKUP attribute of START DATABASE
naming menu options 7-150
PERFORM 4-63 statement 3-42
requesting help from 7-151
Looping statements 5-4 MODIFY keyword, ALTER TABLE
selecting options 7-152
FOR 2-18, 7-38, 7-104 statement 7-15
Message line 2-19, 7-154
FOREACH 2-18, 3-16, 7-106 Modify option
MESSAGE LINE keywords
WHILE 2-19, 3-27, 7-216 FORM Menu 1-15, 1-44, 4-61
OPEN WINDOW
Lowercase characters MODULE Menu 1-9, 1-39
statement 7-161
DOWNSHIFT attribute 4-32, E-39 PROGRAM Menu 1-19, 1-49
OPTIONS statement 7-154, 7-165
downshift function 6-9

14 Index
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

Module 2-18 PROGRAM Menu 1-22, 1-51 NULL values

compiling 1-13, 1-42 NEWLINE character 4-47, E-11 aggregate functions 3-55, 3-64,
option of INFORMIX-4GL NEXT FIELD clause 5-46, 7-250
Menu 1-9, 1-38 INPUT ARRAY statement 7-130 assigning 7-120
running multi-module Next key 7-166, I-5, I-23 definition of 2-5, 3-53
programs 1-13, 1-42, 1-65 NEXT keyword in Boolean expressions 2-14, 3-55,
MODULE Menu 1-26, 1-55 FETCH statement 3-22, 7-98 7-118, 7-229
Module variables 2-4 MENU statement 7-150 in columns 3-54, 7-144, 7-234
MONEY data type OPTIONS statement 7-166 in display fields 4-19, 4-29, 4-40
acceptable values 3-9, 7-50 NO keyword in GROUP BY clause 3-56, 7-240
in dbload input files E-12 CREATE TABLE statement 7-50 in joined columns 3-56, G-3
with database columns 3-9 OPTIONS statement 7-166 in number expressions 3-54
with display fields 4-29, C-5 SELECT statement 7-245 in ORDER BY clause 3-56
with variables 2-8, 7-71 syscolval table 4-57 in string expressions 3-54, 4-29
MONTH keyword NO WRAP keywords, OPTIONS in WHERE clause 3-55, 7-228
DATETIME qualifier 3-10, J-2 statement 7-166 NOT NULL clause 3-54, 7-51,
INTERVAL qualifier 3-10, J-5 NOENTRY attribute 4-37 7-228
MONTH( ) function 2-40, 7-9, NORMAL attribute 4-59, 7-77, truth tables 3-55
7-255 7-154 with dbload utility E-12
Multiple-column fields 4-21, 4-34, NOT FOUND keywords with INSERT 3-57
4-42 WHENEVER statement 2-22, with UPDATE 3-57
Multiple-database queries Intro-7 7-213 WITHOUT NULL INPUT 4-7
Multiple-line fields 4-20, 4-47 NOT keyword Number expression 2-11
Multiple-module programs, ALTER INDEX statement 3-53, arithmetic operators in 2-11
compiling 1-13, 1-27, 1-41, 1-50, 7-12 formatting 2-44, 4-33
1-56, 1-64 Boolean operator 2-13, 3-55, 7-218 NULL values in 3-54
Multiple-statement prepared SELECT statement 7-238 Number of rows processed 3-63
objects 3-38, 7-172 SET LOCK MODE NUMERIC data type 2-8, 3-9
Multiple-table forms 4-56 statement 7-197 num_args function 6-17
Multiple-table view 3-60, 7-58 WHERE clause 7-229
NOT NULL keywords
ALTER TABLE statement 3-54, O
N 7-14
O symbol Intro-11
CREATE TABLE statement 3-54
Naming conventions Object file 1-35, 1-50, 1-72, E-30
dbload utility E-14
column 3-6, 7-51 Object, naming in MODE ANSI
dbupdate utility E-25
constraints 3-7, 7-49 database 3-7
FORMONLY fields 4-19
database 3-6, 7-41 OF keyword
SELECT statement 2-13, 7-228
display fields 4-17, 4-18, 4-22 AFTER GROUP OF control
NOTFOUND code, status
field tags 4-11 block 5-25
variable 3-63
identifiers 2-4, 3-6 ARRAY data type 2-10
NOTFOUND keyword
objects in a MODE ANSI BEFORE GROUP OF control
status after FETCH 3-17, 3-22
database 3-7 block 5-27
status after SELECT 3-63
table 3-6, 7-51 DECLARE statement 3-17, 7-64
NOUPDATE attribute of
NEED statement in REPORT DELETE statement 3-18, 7-73
PERFORM 4-63
statement 5-38 UPDATE statement 3-19, 7-207
NULL keyword
New option OFF keyword, SET EXPLAIN 7-194
dbload command file E-13
FORM Menu 1-17, 1-46 ON EVERY ROW control
INITIALIZE statement 2-15
MODULE Menu 1-12, 1-41 block 5-31

Index 15
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

ON KEY clause OPTIONS statement 2-20 START DATABASE

DISPLAY ARRAY mkmessage utility E-27 statement 7-200
statement 7-60, 7-79 syntax and notes 7-165 VALIDATE statement 7-211
INPUT ARRAY statement 7-130 OR keyword Owner of an object in a MODE
INPUT statement 6-22, 7-123 Boolean operator 2-13, 3-55 ANSI database 4-4, 4-60, 7-16,
PROMPT statement 7-173 COLOR attribute 4-25 7-35
ON keyword in WHERE clause 3-56, 7-234
CONSTRUCT statement 7-32 ORDER BY clause
DISPLAY ARRAY statement 7-79 ASC 3-56, 7-243 P
GRANT statement 7-115 DESC 3-56, 7-243
PAGE HEADER control block 5-29,
PROMPT statement 7-173 INSERT statement 7-139
5-34
REPORT statement 5-8 multiple-column sorting 7-243
PAGE keyword
REVOKE statement 7-187 prohibited in view definition 7-58
FIRST PAGE HEADER control
SET EXPLAIN statement 3-52, REPORT statement 5-18, 5-25
block 5-29
7-194 SELECT statement 7-243
PAGE HEADER control
ON LAST ROW control block 5-33 with NULL values 3-56
block 5-34
OnLine database engine Intro-6, orders table in stores
PAGE LENGTH statement 5-17
7-7, C-7 database Intro-11, A-3
PAGE TRAILER control
OPEN FORM statement 2-20 OTHERWISE keyword
block 5-36
opening a closed form 7-28 CASE statement 7-21
SKIP statement 5-43
syntax and notes 7-159 Outer joins 3-61, G-1
PAGE LENGTH statement 5-17
OPEN statement OUTER keyword, SELECT
PAGE TRAILER control block 5-36
syntax and notes 7-156 statement 3-62, 7-8, 7-218, 7-226,
PAGENO expression 5-49
USING clause 3-36, 7-157 G-3
Pages
with a SELECT cursor 3-16 OUTPUT section of REPORT
of a help file message E-28
with an INSERT cursor 3-26, statement 5-9
of a report 5-9
7-157 BOTTOM MARGIN 5-16
of a screen form 4-9, 4-63
OPEN WINDOW statement 2-20 LEFT MARGIN 5-12
of menu options 7-150
ATTRIBUTE clause 7-161 PAGE LENGTH 5-17
Parameters of functions 2-56, 7-110
syntax and notes 7-160 REPORT TO 5-10
Parentheses
Operating system REPORT TO PRINTER 5-10
in syntax statements Intro-10
invoking the Compiler from 1-32, RIGHT MARGIN 5-13
in USING format strings 2-45
1-61 syntax 5-9, 7-184
Pattern matching
invoking the Programmers TOP MARGIN 5-15
query by example 7-33
Environment from 1-25, 1-30, OUTPUT TO REPORT
with equal ( = ) sign 7-33
1-54, 1-59 statement 2-21
with LIKE 2-13, 7-231
Operator guidelines for using 5-4
with MATCHES 2-13, 7-232
arithmetic 2-11 syntax and notes 7-170
PAUSE statement, REPORT
range 7-34, 7-233 Overflow of a display field 2-46
statement 5-39
relational 2-13 Owner naming 3-7, 7-226
P-code compiler, function 1-61
string 2-12 ALTER TABLE statement 7-15
P-code runner 1-61
UNION 7-246 and system catalogs 3-8
customized 1-68, 1-69
OPTION keyword CREATE SYNONYM
Interactive Debugger 1-59
CREATE VIEW statement 3-60, statement 7-47
specifying name and
7-57 CREATE TABLE statement 7-51
location 1-50
GRANT statement 7-116 CREATE VIEW statement 7-57
P-code version number 1-62, 1-64
MENU statement 7-150 FORM4GL specification 4-15
PERCENT aggregate function 5-46
Options of 4GL menus 7-150 INITIALIZE statement 7-120

16 Index
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

PERFORM (INFORMIX-SQL) CLIPPED 2-27 INFORMIX-4GL language

screens with INFORMIX- COLUMN 2-29 overview 2-3
4GL 4-3, 4-63 REPORT statement 5-40 lettercase sensitivity 4-11
Period ( . ) symbol USING 2-48 looping statements 3-24
delimiter in DATETIME PRINTER keyword MAIN program block 2-17, 7-148
values 2-6, E-12 REPORT TO statement 5-10 menus 7-149
delimiter in INTERVAL START REPORT statement 7-202 multi-module programs 1-13,
values 2-6, E-12 PRIOR keyword, FETCH 1-41
in help message source files E-27 statement 3-17, 7-98 owner naming 4-15
in USING format string 2-45 PRIVILEGES keyword 7-115 program arrays 2-10
prefix separator 2-24, 4-14 Process isolation Intro-7 program flow statements 2-18,
range operator 7-34 Program array 7-5
PICTURE attribute 4-38, 4-57 array of records 2-10 records 4-54, 7-71, 7-138
PIPE keyword arr_count function 6-6 reports 2-21, 5-3, 7-184
REPORT TO statement 5-10 arr_curr function 6-7 running, at operating system
START REPORT statement 7-202 defining 2-10, 7-71 level 1-64
Planned_Compile option, displaying rows in 7-79 screen interaction
PROGRAM Menu 1-23, 1-52 inserting rows 7-131 statements 2-19, 7-165
Plus ( + ) sign set_count function 6-20 statement types 2-16, 3-10, 7-5
arithmetic operator 2-11, 7-219 table of functions for 7-135 transactions 3-42
in USING format strings 2-45 Program examples types of program modules 1-10,
in window border 7-163, I-6 that call C functions 1-70, 2-57 1-21, 1-29, 1-32, 1-50, 1-69
unary operator 2-5, 2-6 Program execution Program flow statements 2-18, 7-5
Popping functions (C commencing 1-59, 1-65, 6-4, 6-17 Program module, definition of 2-18
language) 2-55 from the command line 1-6, 6-4 Program organization
Pound ( # ) sign programs that call C statements 2-17, 7-5
comment indicator 2-3, I-3 functions 1-34, 1-66 Program records 7-72, 7-138
in FORMAT format strings 4-33 terminating 6-12, 7-97 Program specification
in PICTURE format strings 4-38 with the Interactive database 1-18, 1-48
in USING format strings 2-44 Debugger 1-65, 1-72 Programmers Environment
PREPARE statement 3-28 Program features accessing 1-6, 1-7, 1-37
executing 3-33, 7-94 assignment statements 2-17 COMPILE FORM Menu 1-16,
guidelines for using 3-28 calling C functions 1-66, 2-55, 1-45
multiple SQL statements 3-38, 7-19 COMPILE MODULE Menu 1-10,
7-172 commenting 2-3 1-39
syntax and notes 7-171 compiler 1-25, 1-32, 1-39 COMPILE PROGRAM
using placeholders for compiling through Programmers Menu 1-22, 1-51
values 3-30 Environment 1-10, 4-60 compiling a form 1-27, 1-56, 4-61
with a character string 3-30 compiling, at operating system compiling a program 1-12, 1-27,
with a character variable 3-31 level 1-61 1-41, 1-56
Preprocessor, invoking 1-31, 1-32 conditional statements 4-25, 7-21, correcting errors in a
Previous key 7-166, I-5, I-23 7-118 program 1-11, 1-40
PREVIOUS keyword error messages 2-21, 6-10, E-29 creating a default form 4-61
FETCH statement 3-23, 7-98 executing a non-4GL Debug option, MODULE
OPTIONS statement 7-166 process 7-191 Menu 1-42
PRINT FILE statement in expressions 2-11 Debug option, PROGRAM
reports 5-42 functions 2-24, 2-55, 6-3, 7-110 Menu 1-53
PRINT statement help messages 6-21, 7-166, E-27 defining a program 1-26, 1-55
identifiers 2-4 definition of 1-6

Index 17
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

Drop option, PROGRAM PUBLIC keyword QUIT keyword, DEFER

Menu 1-24 GRANT statement 3-41, 7-52, statement 7-69
Exit option, FORM Menu 1-18, 7-116 quit_flag variable 2-23, 7-69
1-47 REVOKE statement 7-52, 7-188 Quotation ( " ) marks
Exit option, MODULE Pushing functions (C around character pointer 1-68
Menu 1-14, 1-43 language) 2-55 around character strings 2-5, 4-36
Exit option, PROGRAM PUT statement around date-time value 2-6, 4-29
Menu 1-24, 1-53 and the SQLCA record 3-28, around format strings 2-44, 2-46,
files displayed 1-26, 1-64 7-178 4-33, 4-38
FORM Menu 1-14, 1-43, 4-61 and the status variable 3-28, 7-178 around pathnames 7-39, 7-50,
Generate option, FORM FROM clause 3-38 7-200
Menu 1-16, 1-46 guidelines for using 3-26, 7-26
in C Compiler version of 4GL 1-7 syntax and notes 7-177
in Rapid Development R
System 1-36
r4gl command 1-6, 1-54, 4-61
INFORMIX-4GL Menu 1-8, 1-37 Q r4gldemo script Intro-11, 1-6
invoking the Debugger 1-38, 1-53
Query by example Range of values
menu options 1-31, 1-61
CONSTRUCT 7-33 COLOR attribute 4-25
modifying a form specification
PREPARE 3-30 dbload utility E-14
file 1-15, 1-44
table of operators 7-33 INCLUDE attribute 4-35
MODULE Menu 1-9, 1-38
using the alternation query by example 7-34
NEW FORM Menu 1-17, 1-46
operator 7-33 upscol utility 4-58, E-41
NEW MODULE Menu 1-12, 1-41
using the range operator 7-34 WHERE clause 7-229
NEW PROGRAM Menu 1-22,
using wildcard characters 7-34 Rapid Development System version
1-51
Query optimizer 3-52, 7-194 of 4GL Intro-3, 1-5, 1-36
Planned_Compile option,
QUERYCLEAR attribute of RDS (= Rapid Development
PROGRAM Menu 1-23, 1-52
PERFORM 4-63 System) 1-5
PROGRAM Menu 1-18, 1-48
Querying the database REAL data type 2-8, 3-9
Program_Compile option,
compound queries 7-246 Record
MODULE Menu 1-13, 1-41
cursors 3-13, 7-64, 7-156 definition of 2-9, 7-71
QUERY LANGUAGE Menu 1-25,
distributed across in an array 4-54, 7-192
1-54
databases Intro-7 passing to a function 7-111
Run option, MODULE
joins 3-51, 4-63, 7-234, G-1 SQLCA global record 3-63
Menu 1-13, 1-42
query by example 7-32 with INSERT 7-138
Run option, PROGRAM
relational operators 7-220 RECORD keyword
Menu 1-24, 1-52
searching for rows with NULL defining program records 2-9,
Undefine option, PROGRAM
values 3-56 7-71
Menu 1-53
subqueries 3-56, 7-207, 7-237 defining screen arrays 4-55
Program_Compile option,
through views 3-58 defining screen records 4-54
MODULE Menu 1-13, 1-41
with SELECT 7-218 defining variables 7-71
PROMPT LINE keywords
Question ( ? ) mark LIKE keyword 2-9, 7-71
OPEN WINDOW
placeholder in PREPAREd Records in data files 7-143, 7-203,
statement 7-161
statements 3-30, 7-94, 7-171, E-12
OPTIONS statement 7-165
7-178 RECOVER TABLE statement 3-46,
Prompt line of a screen form 7-162
wildcard 7-34, 7-232 7-179
PROMPT statement 2-19
Quick Reference Card Intro-3 Recovery procedures Intro-7, 3-42
syntax and notes 7-173
Quit key 2-23, 7-69 RED attribute 4-26, 4-59, 7-77, I-19
Pseudo-code (= p-code) 1-5

18 Index
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

Relational operators 2-13, 4-25, Reserved lines ROW keyword

7-220 Comment line 4-27, 7-165 EVERY ROW statement 5-21
RELATIVE keyword default settings 7-161 INPUT ARRAY statement 7-130
FETCH statement 3-17, 7-98 Error line 2-19, 2-23, 6-11, 6-12, ON EVERY ROW control
RENAME COLUMN 7-162, 7-165 block 5-31
statement 3-12 Form line 2-20, 7-162, 7-166 ON LAST ROW control
syntax and notes 7-181 Message line 2-19, 7-165 block 5-33
RENAME TABLE statement 3-11 Prompt line 2-19, 7-165 Row number
syntax and notes 7-182 Reserved words in a database table 3-62
Report generation statements 2-21, listing D-1 in a program array 6-7, 6-20
7-5 RESOURCE access privilege 7-116 in a screen array 4-55, 6-18
REPORT statement 2-18 RESOURCE keyword ROWID value 3-62, 3-64
aggregate functions 5-44 GRANT statement 3-41, 7-116 ROWS keyword, OPEN WINDOW
control blocks 5-23 REVOKE statement 7-187 statement 7-160
DEFINE section 5-5, 5-7 Return key 7-166 Run menu option 1-31, 1-61
displaying a report 5-9 RETURN keyword Run option
END REPORT keywords 5-5 FUNCTION statement 7-110 MODULE Menu 1-13, 1-42
FORMAT section 5-5, 5-20 RETURN statement 7-186 PROGRAM Menu 1-24, 1-52
grouping data 5-23 RETURNING keyword RUN statement 2-19, 7-191
ORDER BY section 5-5, 5-18 CALL statement 2-56, 7-19 Runner, creating a customized 1-69
ORDER EXTERNAL BY 5-18 RUN statement 7-191 Runner, invoking 1-5, 1-50, 1-61
OUTPUT section 5-5, 5-9 REVERSE attribute 4-26, 4-59, I-9 Running a 4GL program
PRINT statement 5-40 description of 4-42 command line 1-6, 1-34
REPORT keyword 5-6 multiple-column 4-21 that calls C functions 1-34, 1-72
running a report 5-4, 7-202 REVOKE statement 3-40 using Debugger 1-61, 7-7
SKIP statement 5-43 DBA 3-41 Run-time errors 2-21, 7-213
statements in a report syntax and notes 7-187
routine 5-37 RIGHT attribute of PERFORM 4-63
structure 5-5 RIGHT MARGIN statement 5-13 S
syntax and notes 7-184 Ring menu 7-150
Schema language 7-10
REPORT TO statement 5-10 ROLLBACK WORK statement
Schema replication, using
Report writer 5-3 restoring previous database 3-42
dbschema E-22
Reports, programmer-defined syntax and notes 7-189
Scope of reference of identifiers 2-5
aggregate functions 5-26 ROLLFORWARD DATABASE
Screen array 7-32, 7-75
calculations on groups 5-47 statement
definition of 4-55
counting rows 5-46 definition of 3-42
format of 4-12, 4-56
default layout 5-21 recovering a database 3-45
identifying the current row 6-7,
features 5-3 syntax and notes 7-190
6-18
formatting 5-20, 5-23, 7-184 Row 3-5
keys for scrolling and
minimal report 5-6 deleting from a table 3-18, 7-73
editing 7-131
output of a report 5-9 determining row length E-24
scrolling rows of data 7-192
piping a report to a program 5-10 duplicates in a view 3-60
table of functions for 6-3, 7-135
printing data 5-40 inserting into a table 7-138
Screen display characteristics
running a report 5-4 locking 3-48, 7-99, 7-139
changing attributes 4-59, 7-36,
sending output to a file 5-10 ROWID 3-62
7-77, 7-81, 7-83, 7-93, 7-127,
sorting data 5-18, 7-185 unlocking 3-48
7-136, 7-155, 7-168, 7-175
starting report processing 7-202 updating 3-19, E-38
clearing the screen 7-23, I-4, I-22
steps for creating 5-4
REQUIRED attribute 4-40

Index 19
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

default screen attributes 4-56, SECOND keyword joining columns with 3-51, 7-234
E-40 DATETIME qualifier 3-10, J-2 LENGTH function 2-38, 7-251
screen coordinates 4-8, 7-76, INTERVAL qualifier 3-10, J-6 ORDER BY clause 3-18, 7-243
7-161 SELECT clause overview of clauses 7-220
setting up screen attributes 4-22 ALL 7-222 relational operators 7-220
table of color and intensity display label 7-8, 7-222 SELECT clause 7-222
values 4-57 DISTINCT and UNIQUE self-join 7-235
Screen form 4-5 keywords 7-222 singleton SELECTs 7-224
clearing values in the form 7-23 join conditions 7-234, G-1, G-4 syntax and notes 7-193, 7-218
closing 7-28 syntax and notes 7-222 UNION operator 7-246
dimensions 4-6, 4-8, 7-161 SELECT cursor using multiple tables 7-220
displaying 7-83, 7-165 advancing 3-17 WHERE clause 7-228
displaying values in fields 7-75 closing 3-17, 7-25 with an outer join 3-62, 7-235, G-1
entering values in fields 7-32 declaring 3-14, 7-64 with multiple joins 7-235, G-5
identifying the current field 6-14 opening 3-16, 7-156 with subqueries 3-56, 7-237
opening a 7-159 syntax and notes 3-13, 7-64 Semicolon ( ; ) symbol
specifying from the Programmers SELECT keyword in multiple-column display
Environment 1-14, 1-43, 4-61 dbload command file E-12 fields 4-21
Screen interaction statements 2-19, DECLARE statement 3-14, 7-64 in the description of a display
7-5 GRANT statement 3-41, 3-60, field 4-16
SCREEN keyword 7-115, 7-204 statement terminator 7-172, E-14
CLEAR statement 7-23 REVOKE statement 3-41, 7-187 SEQUENTIAL SCAN access
CURRENT WINDOW SELECT statement method 7-194
statement 7-60 aggregate functions in 7-249 SERIAL data type
INSTRUCTIONS section of form arithmetic operators in 7-219 acceptable values 3-9, 7-51
specification 4-4, 4-54 assigning a cursor 3-14, 7-64 INSERT statement 4-37, 7-139
SCREEN section of form constructing with LET 7-172 program variables 2-9
specification 4-8 creating temporary tables 7-8, retrieved by
Screen record 7-32, 7-75 7-245 SQLCA.SQLERRD[2] 3-63
default screen record 4-54 DATETIME or INTERVAL UPDATE statement 7-207
definition of 4-54 values J-15 with database columns 3-9
moving rows through a screen defining a view 3-58, 7-57 with display fields 4-19, 4-37
array 7-192 definition of 3-12, 7-193 SET EXPLAIN statement 3-52
SCREEN RECORD keywords 4-54 displaying results 5-3 syntax and notes 7-194
SCREEN section of form distributed across with joins G-10
specification databases Intro-7 SET keyword, UPDATE
definition of 4-8 estimating CPU cost 3-52, 7-194 statement 7-206
display field 4-10 expression in 7-219 SET LOCK MODE statement 3-48,
field delimiters 4-11, 4-52 FROM clause 7-226 7-197
field tags 4-10 functions in 2-24, 7-248 kernel locking 3-50
field width 4-11 GROUP BY clause 7-8, 7-240 set_count function
for a multiple-table form 4-6 HAVING clause 7-242 guidelines for using 7-80
graphics characters 4-12 in a DECLARE statement 7-64 syntax and usage 6-20
screen page layout 4-9 in an INSERT statement 7-138 with INPUT ARRAY 7-135
Screen-building utility 4-3 in an UNLOAD statement 7-203 sg1 terminal specification 7-77,
SCROLL keyword INTO clause 3-29, 7-99, 7-107, 7-127, 7-136, 7-176, I-4, I-18
DECLARE statement 3-14, 7-64 7-224 SHARE keyword
SCROLL statement 2-21, 7-192 INTO TEMP clause 3-58, 7-8, LOCK TABLE statement 3-49,
scr_line function 6-18, 7-135 7-245 7-146

20 Index
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

Shared memory Intro-6, 3-48, 7-197 CREATE AUDIT statement 3-45, REVOKE statement 3-40, 7-187
SHIFT attribute 4-57 7-39, 7-179 ROLLBACK WORK
showhelp function 6-21, E-29 CREATE DATABASE statement 7-189
Single-field INTERVAL value 2-6, statement 3-11, 7-41 ROLLFORWARD DATABASE
4-30 CREATE INDEX statement 3-12, statement 7-190
SIZE keyword, form 7-44 SELECT statement 3-12, 7-64,
specification 4-9 CREATE SCHEMA 7-193, 7-203, 7-218
SKIP statement in reports 5-43 AUTHORIZATION SET EXPLAIN statement 7-194
SLEEP statement 2-19, 7-199 statement 7-10 SET LOCK MODE
SMALLFLOAT data type CREATE SYNONYM statement 7-197
acceptable values 2-8, 3-9, 7-50 statement 3-11, 7-47 START DATABASE
REAL synonym 2-8, 3-9 CREATE TABLE statement 3-11, statement 7-200
with database columns 3-9 7-49 UNLOAD statement 3-12, 7-203,
with FORMAT attribute 4-33 CREATE VIEW statement 3-11, E-11
with variables 2-8, 7-71 7-57 UNLOCK TABLE statement 3-40,
SMALLINT data type DATABASE statement 3-11, 7-62 7-205
acceptable values 2-7, 3-8, 7-50 DECLARE statement 3-14, 3-26, UPDATE statement 3-12, 7-206
with database columns 3-8 3-29, 7-64 UPDATE STATISTICS
with variables 2-7, 7-71 DELETE statement 3-12, 7-73 statement 3-12, 7-210
SOME keyword, SELECT DROP AUDIT statement 3-45, WHENEVER statement 2-21,
statement 7-237 7-85, 7-179 7-213
Sorting data DROP DATABASE SQL language 3-5
DATE columns 7-52 statement 3-11, 7-86 accessing from the Programmers
in a report 5-18 DROP INDEX statement 3-12, Environment 1-25, 1-54
in an index 7-12 7-88 ambiguity with INFORMIX-4GL
multiple-column sorting 7-243 DROP SYNONYM identifiers 3-7
with NULL values 3-56 statement 3-12, 7-89 audit trails 3-45, 7-39, 7-85, 7-179
with ORDER BY 5-25, 7-243 DROP TABLE statement 3-11, data access statements 3-40, 7-6
Source modules 1-32, 1-61, 1-63 7-90 data definition statements 3-11,
Source path 1-50, C-6 DROP VIEW statement 3-11, 7-91 7-6
SPACE keyword 5-50 EXECUTE statement 3-28, 7-94 data integrity statements 3-42, 7-6
Spacebar 7-150 FETCH statement 3-16, 7-98 data manipulation
Spaces FLUSH statement 3-26, 7-102 statements 3-12, 7-6
in WORDWRAP fields 5-52 FOREACH statement 3-16 dynamic management
SPACES keyword 5-50 FREE statement 3-39, 7-109 statements 3-28
sqexplain.out file 3-52, 7-194 GRANT statement 3-40, 7-115 identifiers 3-6, 3-28
SQL INSERT statement 3-12, 7-138 interactive query language 1-8,
ALTER INDEX statement 3-12, LOAD statement 3-12, 7-143 1-37, 3-5, 4-63
7-12 LOCK TABLE statement 3-40, statements supported only on
ALTER TABLE statement 3-11, 7-146 INFORMIX-SE 7-6
7-14 OPEN statement 3-16, 3-26 testing statement execution 3-63
BEGIN WORK statement 3-43, PREPARE statement 3-28, 7-171 transactions 3-42
7-18 PUT statement 3-26, 7-177 update notes for Version 1.10
CLOSE DATABASE RECOVER TABLE users 3-54
statement 3-11, 7-27 statement 3-46, 7-179 SQL version number 1-33, 1-62
CLOSE statement 3-17, 3-26 RENAME COLUMN SQLAWARN characters 3-6, 3-64,
COMMIT WORK statement 3-43, statement 3-12, 7-181 7-213
7-31 RENAME TABLE statement 3-11,
7-182

Index 21
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

SQLCA record DATABASE 7-62 REPORT 7-184

definition of 3-63 DECLARE 7-64 RETURN 7-186
examined by WHENEVER 2-22 DEFER 7-69 REVOKE 7-187
set by CLOSE 3-28 DEFINE 7-71 ROLLBACK WORK 7-189
set by FLUSH 3-28 DELETE 7-73 ROLLFORWARD
set by PUT 3-28, 7-178 DISPLAY 7-75 DATABASE 7-190
SQLAWARN 3-6, 3-64, 7-213 DISPLAY ARRAY 7-79 RUN 7-191
SQLCODE 3-17, 3-63, 7-145, 7-178 DISPLAY FORM 7-83 SCROLL 7-192
SQLERRD 3-28, 3-63, 7-25, 7-145, DROP AUDIT 7-85 SELECT 7-193, 7-218
7-157 DROP DATABASE 7-86 SET EXPLAIN 7-194
sqlconv utility E-31 DROP INDEX 7-88 SET LOCK MODE 7-197
SQLERROR keyword 7-213 DROP SYNONYM 7-89 SLEEP 7-199
SQLEXEC environment DROP TABLE 7-90 START DATABASE 7-200
variable C-7 DROP VIEW 7-91 START REPORT 7-202
SQLWARNING keyword 7-213 ERROR 7-92 UNLOAD 7-203
Stack, in calling C functions 2-55 EXECUTE 7-94 UNLOCK TABLE 7-205
START DATABASE statement 3-42 EXIT 7-96 UPDATE 7-206
syntax and notes 7-200 FETCH 7-98 UPDATE STATISTICS 7-210
WITH LOG IN 3-43 FINISH REPORT 7-101 VALIDATE 7-211
START REPORT statement 2-21 FLUSH 7-102 WHENEVER 7-213
directing output 5-10 FOR 7-104 WHILE 7-216
syntax and notes 7-202 FOREACH 7-106 Statement type
startlog function 2-22, 6-23 FREE 7-109 assignment 2-17, 7-5
state table in stores FUNCTION 7-110 cursor manipulation 3-13, 7-6
database Intro-12, A-4 GLOBALS 7-112 data access 3-40, 7-6
Statement identifier 3-28, 7-94, GOTO 7-114 data definition 3-11, 7-6
7-109 GRANT 7-115 data integrity 3-42, 7-6
Statement label 7-114, 7-141, 7-213 IF 7-118 data manipulation 3-12, 7-6
Statement syntax INITIALIZE 7-120 data validation 2-23
ALTER INDEX 7-12 INPUT 7-122 dynamic management 3-28, 7-6
ALTER TABLE 7-14 INPUT ARRAY 7-129 error and exception
BEGIN WORK 7-18 INSERT 7-138 handling 2-21
CALL 7-19 LABEL 7-141 program flow 2-18, 7-5
CASE 7-21 LET 7-142 program organization 2-17, 7-5
CLEAR 7-23 LOAD 7-143 report generation 2-21, 7-5
CLOSE 7-25 LOCK TABLE 7-146 screen interaction 2-19, 7-5
CLOSE DATABASE 7-27 MAIN 7-148 variable definition 2-17, 7-5
CLOSE FORM 7-28 MESSAGE 7-154 status variable 2-22
CLOSE WINDOW 7-30 OPEN 7-156 definition of 3-63
COMMIT WORK 7-31 OPEN FORM 7-159 NOTFOUND code 2-22, 3-17,
CONSTRUCT 7-32 OPEN WINDOW 7-160 3-22, 7-99, 7-213
CONTINUE 7-38 OPTIONS 7-165 with cursors 3-28
CREATE AUDIT 7-39 OUTPUT TO REPORT 7-170 with err_get function 6-10
CREATE DATABASE 7-41 PREPARE 7-171 with err_print function 6-11
CREATE INDEX 7-44 PROMPT 7-173 with err_quit function 6-12
CREATE SYNONYM 7-47 PUT 7-177 with INITIALIZE 7-121
CREATE TABLE 7-49 RECOVER TABLE 7-179 with VALIDATE 7-212
CREATE VIEW 7-57 RENAME COLUMN 7-181 STEP keyword, FOR
CURRENT WINDOW 7-60 RENAME TABLE 7-182 statement 7-104

22 Index
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

stock table in stores schema 4-57 display label 7-223

database Intro-11, A-4 use by FORM4GL 4-17, 4-56 dominant 3-62, G-2
STOP keyword, WHENEVER with DISPLAY LIKE 4-31 filename 7-50, E-2
statement 7-213 syscolval table 2-24, 4-56 guidelines for indexing 3-51
stores database as used by INITIALIZE 4-58, joining tables 3-52, 7-234, A-5,
customer table Intro-11, A-2 7-121 G-2
data values A-9 comparing values of locking 3-49, 7-146, 7-208, E-19
items table Intro-11, A-3 variables 7-211 modifying a row 3-59, 7-206
join columns A-5 creating with upscol 4-60, E-37 naming conventions 3-6, 7-51
manufact table Intro-11, A-4 data validation 2-23, 4-58, 7-211 not logging temporary 7-50
orders table Intro-11, A-3 schema 4-57 outer join 3-61, 7-235, G-1
overview A-1 use by FORM4GL 4-17, 4-56 removing a column 7-14
state table Intro-12, A-4 with VALIDATE LIKE removing a constraint 7-16
stock table Intro-11, A-4 attribute 4-45 removing a synonym 3-12, 7-89
structure of tables A-2, A-5 syspgm4gl files 1-18, 1-48 removing a table 7-90
tables in Intro-11, A-2 System catalogs renaming 7-182
String expression 2-12 creating 3-11, 7-41 revoking user access 7-188
CLIPPED keyword 2-27 described 3-5, B-1 rules for owner naming 3-7
concatenation operator 7-172 querying when MODE ANSI 3-8 structure in stores database A-2
constants 2-5 syscolauth B-3 subservient 3-62, G-2
length 2-38, 7-251 syscolumns 3-58, 7-138, B-2 temporary 3-58, 7-223, 7-245,
NULL values in 4-19 sysconstraints 7-16, 7-53, B-5 7-247
substring 2-12, 4-18 sysdepend B-4 unlocking 3-40, 3-47, 7-205
table of operators 2-12 sysindexes B-3 TABLES section of form
USING keyword 2-44 syssynonyms B-4 specification
Structure definition file, syssyntable B-5 definition of 4-4, 4-14
function 1-66 systabauth B-3 Tape block size E-6
Subquery 3-56, 3-59, 7-222, 7-237, systables 4-15, 7-210, B-2 TEMP keyword
7-247 sysusers B-4 CREATE TABLE statement 7-10,
Subscript sysviews 3-58, B-5 7-49
evaluating with cursors 7-67 updating 3-12 SELECT statement 3-58, 7-8,
of a CHAR column 4-18, 7-220 7-245
Substring 2-12, 4-18, 7-142 termcap file 4-13, I-2
SUM aggregate function 2-48, 3-64, T TERMINFO environment
5-46, 7-249 variable I-20, I-25
Table 3-5
Synonym terminfo files 4-13, I-20
access methods 3-52, 7-194
for a table 3-11, 7-47, 7-226, E-22 TEXT data type Intro-7
access privileges 3-41, 7-115, E-22
removing a synonym 3-12, 7-89 Text editor 1-11, 1-15, 1-31, 1-40,
adding a column 7-14
rules for owner naming 3-7 1-45, 1-61
adding a constraint 7-16
Syntax checking, ANSI 1-32, 1-62, THEN keyword, IF statement 7-118
adding a row 7-138, 7-143, E-11
3-6 THROUGH keyword 2-15, 4-55
alias for table name 4-14, 4-60,
Syntax conventions Intro-9 THRU keyword 2-15, 4-55
7-35, 7-226
Syntax of command line to compile TIME function 2-41
audit trails 3-42, 7-39
a 4GL source file 1-32, 1-61 TO keyword
changing the data type of a
syscolatt table 4-56 ALTER INDEX statement 3-53,
column 7-14
changing color names 4-58, I-19 7-12
creating 7-49, E-22
color and intensity values 4-57, CURRENT function 2-30, 7-258
creating a synonym 7-47, E-22
E-40 DATETIME literals 2-6, 4-30, J-2
current 4-63
creating with upscol 4-60, E-37 DISPLAY ARRAY statement 7-79

Index 23
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

DISPLAY statement 2-15 Twenty-Minute Guide Intro-3 WHERE CURRENT OF

EXTEND function 2-35, 7-260 TYPE keyword, FORMONLY clause 3-19
GRANT statement 3-32, 7-115 fields 4-19 with NULL values 3-57
INCLUDE attribute 4-35 UPDATE STATISTICS
INITIALIZE statement 2-15, statement 3-12, 7-210
7-120 U UPDATE SYSCOL Menu
INTERVAL literals 2-6, 4-30, J-5 (upscol) E-37
Undefine option, PROGRAM
RENAME COLUMN Uppercase characters
Menu 1-53
statement 7-181 DOWNSHIFT attribute 4-32, E-39
UNDERLINE attribute 4-26, 4-59,
RENAME TABLE downshift function 6-9
I-9
statement 7-182 in 4GL statements 2-3, 4-11
UNION operator 3-58, 7-58, 7-246
REPORT TO statement 5-10 in syntax statements Intro-10
UNIQUE constraint 7-139, E-14
SET LOCK MODE SHIFT attribute 4-57, E-39
UNIQUE keyword
statement 3-50, 7-197 UPSHIFT attribute 4-43, E-39
aggregate functions 7-250
SKIP statement 5-43 upshift function 6-25
ALTER TABLE statement 7-14
START REPORT statement 7-202 upscol utility 2-24, 4-59, E-37
CREATE INDEX statement 7-44
UNLOAD statement 7-203 UPSHIFT attribute 4-43, 7-35, E-39
CREATE TABLE statement 7-49
WHENEVER statement 7-213 upshift function 6-25
SELECT statement 7-8, 7-222
TODAY function 2-42, 3-65, 4-30 USER function 3-65, 7-219
UNITS keyword 2-43, 4-30, J-13
TOP MARGIN statement 5-15, 5-29 User status and privileges 3-41
SELECT statement 7-8
TOP OF PAGE keywords 5-43 USING keyword
UNIX permissions E-14
TRAILER keyword, REPORT DISPLAY statement 7-76
UNKNOWN (Boolean
statement 5-36 EXECUTE statement 3-33, 7-94
constant) 2-14, 3-55
Transaction OPEN statement 3-36, 7-156
UNLOAD statement 3-29, 7-203,
committing modifications 3-42, PRINT statement 2-47, 5-40
E-11
7-31 string operator 2-44
UNLOCK TABLE statement 3-40,
comparison with audit trails 3-47 Utility programs
3-47
cycle 3-43 bcheck E-2
syntax and notes 7-205
definition of 3-42 dbexport E-6
UP keyword
explicit 3-44, 7-41, 7-200 dbload E-11, E-33
SCROLL statement 7-192
implicit 3-43, 7-41, 7-200 dbschema E-22
syscolval table 4-57, E-39
log 3-43, 7-42, 7-200 dbupdate E-25
UPDATE keyword
log file maintenance 3-45 mkmessage E-27
DECLARE statement 3-17, 7-64
recovering transactions 3-42, sqlconv E-31
GRANT statement 3-41, 7-115
7-190 upscol 2-24, 4-56, E-37
REVOKE statement 7-187
row locking 3-44, 7-139
UPDATE STATISTICS
singleton 3-44, 7-139
statement 7-210
starting 3-44, 7-18
UPDATE statement
V
statements for specifying 3-42
data conversion in 7-208 V command-line option 1-33, 1-62
undoing modifications 3-42,
DATETIME or INTERVAL VALIDATE LIKE attribute 4-15,
7-189
values J-15 4-45
usage in MODE ANSI 3-43
examples 3-18 VALIDATE Menu (upscol) E-39
Transfer of database files E-6, E-11
functions in 7-248 VALIDATE statement 2-24, 4-58,
TRUE (Boolean constant) 2-5, 3-55,
locking rows 3-48 7-211
4-25
subqueries 7-207 VALUES keyword
Truncation of data 3-64, 4-48, 7-80,
syntax and notes 7-206 dbload command file E-14
E-15
updating through a view 3-59 INSERT statement 7-138
Truth values 2-5, 3-55, 7-237, 7-238
VARCHAR data type Intro-7

24 Index
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

Variable 2-6 rules for owner naming 3-7 with a subquery 7-222, 7-237
as a parameter 2-17, 7-110 virtual column 3-59, 7-58 with COLOR attribute 4-25, 4-63,
binding to database and with duplicate rows 3-60 E-41
forms 2-14 with DELETE 7-73
data types 2-7, 7-71 with SELECT 7-228
declaring a 2-4, 5-5, 7-71 W with UPDATE 7-206
global 2-4, 7-112 WHERE CURRENT OF keywords
WAIT keyword, SET LOCK MODE
in REPORT statement 5-5 DELETE statement 3-18, 7-73
statement 3-50, 7-197
int_flag 2-23, 7-69 UPDATE statement 3-19, 7-207
WARNING keyword, WHENEVER
local 2-4, 7-110 WHILE statement 2-19
statement 2-22, 3-64, 7-213
module 2-4 CONTINUE WHILE 7-38
Warning messages 1-33, 7-7, 7-213
naming conventions 2-4 EXIT WHILE 7-96
WEEKDAY function 2-53, 7-256
quit_flag 2-23, 7-69 syntax and notes 7-216
WHEN keyword, CASE
scope of reference 2-4 WHITE attribute 4-26, 4-59, 7-77,
statement 7-21
statements for assigning I-19
WHENEVER statement
values 2-17 Wildcard character 7-34, 7-232
ERROR keyword 2-22
statements for defining 2-17 Window
guidelines for using 2-22
status variable 2-22, 3-63 attributes 7-161
scope of reference 2-22, 7-214
with the same name 7-111 automatic sizing 7-161
syntax and notes 7-213
Variable definition statements 7-5 border 7-162, I-6, I-24
trapping errors 2-22, E-29
VERIFY attribute 4-46, 4-57 changing the current
trapping warnings and NOT
Version 1 database window 7-60
FOUND 2-22
conversion to Version 2 E-25 clearing of text 7-23
WARNING keyword 2-22, 7-213
Version numbers of SQL clearing the background
WHERE clause
software 1-33, 1-62 screen 7-23
aggregate functions 5-47, 7-248
Versions of 4GL Intro-3, 1-5 closing 7-30
ALL 7-237
Vertical ( | ) bar color 7-163, 7-168
AND 7-234
field separator in files 7-203, E-17 current 7-60, 7-161
ANY 7-237
field separator in forms 4-53 dimensions 7-161
BETWEEN 3-65, 7-229
graphics character 4-13, I-6, I-25 displaying a form 7-161
comparison condition 7-228
in termcap specifications I-3 displaying a menu 7-150
ESCAPE 7-231, 7-233
in window border 7-163, I-6 locating on screen 7-161
EXISTS 7-238
syntax convention Intro-10 multiple windows 7-60
IN 7-230, 7-238
with CONSTRUCT 7-33 opening 7-160
IS NULL 7-234
View reserved lines in 7-161, 7-165
joining columns in 7-234, G-1
access privileges 3-60, 7-117, E-22 stack 7-30, 7-61, 7-164
LIKE 7-231
creating 3-58, 7-57, E-22 WINDOW keyword
MATCHES 7-8, 7-232
creating a synonym 7-47, E-22 CLEAR statement 7-23
NOT 7-218
data constraints 3-60 CURRENT WINDOW
NULL values 3-55, 7-234
definition and uses 3-57, 7-57 statement 7-60
OR 7-234
deleting 3-58, 7-91 OPEN WINDOW
pattern matching in 7-34, 7-232
guidelines for naming 7-58 statement 7-160
ranges in 7-34, 7-229
limitations 3-58, 7-16, 7-57 OPTIONS statement 7-168
relational operators in 2-13, 7-229
modifying the database WITH CHECK OPTION clause
search conditions 7-34, 7-218,
through 3-59 CREATE VIEW statement 3-60,
7-228
querying the database 7-57
sets in 4-58, 7-230
through 3-58 WITH FORM clause, OPEN
SOME 7-237
WINDOW statement 7-161
syntax and notes 7-228

Index 25
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

WITH GRANT OPTION keywords

GRANT statement 3-60, 7-116 X
WITH HOLD keywords X symbol in PICTURE format
DECLARE statement 3-14, 3-20, strings 4-38
7-64 xmc1 terminal specification 7-77,
WITH keyword 7-127, 7-136, 7-176, I-21
CREATE DATABASE XOFF key 7-125
statement 3-43
CREATE TABLE statement 7-50
CREATE VIEW statement 3-60, Y
7-57
DECLARE statement 3-14, 7-64 Y symbol
GRANT statement 3-60, 7-116 formatting DATE values 2-46,
OPEN WINDOW C-3
statement 7-160 option of bcheck utility E-3
START DATABASE values in syscolatt table 4-58, E-40
statement 3-43 YEAR keyword
WITH LOG IN keywords DATETIME qualifier 2-9, 3-10,
CREATE DATABASE 4-20, E-12, J-2, J-5
statement 7-41 INTERVAL qualifier 2-9, 3-10
START DATABASE with CURRENT function 2-31,
statement 7-200 2-36, 7-259
WITH NO LOG keywords with EXTEND function 2-36,
CREATE TABLE statement 7-50 7-260
SELECT statement 7-245 with UNITS keyword 2-43, J-15
WITHOUT DEFAULTS keywords YEAR( ) function 2-54, 7-9, 7-257
INPUT ARRAY statement 4-29, YELLOW attribute 4-26, 4-59, 7-77,
6-20, 7-129 I-19
INPUT statement 4-29, 7-122 YES keyword in syscolval
WITHOUT NULL INPUT table 4-57, E-39
keywords
DATABASE section 4-29
WITHOUT WAITING keywords Z
RUN statement 7-191 ZA function (termcap file) I-9, I-17
WORDWRAP attribute 4-21, 4-47 Zero
WORDWRAP function default INTERVAL value 4-7, J-9
in a PRINT statement 5-40 default number value 4-19
syntax and notes 5-51 for Boolean FALSE 2-14
WORK keyword inserting SERIAL values 7-139
BEGIN WORK statement 3-42, value of status variable 2-22,
7-18 7-213
COMMIT WORK statement 3-42 zero fill ( & ) character in output
ROLLBACK WORK fields 2-46
statement 3-42 Zero or more characters, symbol
WRAP keyword, OPTIONS for 7-34, 7-231, 7-232
statement 7-166 ZEROFILL attribute of
PERFORM 4-63

26 Index

Pro Tools Key Command Preset
No ratings yet
Pro Tools Key Command Preset
3 pages
MSM-Micronetics Standart Mumps - Utility Manual v.4.0 (Micronetics) 1993 Revised
No ratings yet
MSM-Micronetics Standart Mumps - Utility Manual v.4.0 (Micronetics) 1993 Revised
354 pages
Oid
No ratings yet
Oid
36 pages
Insecure Boot: Andrea Barisani - Head of Hardware Security
No ratings yet
Insecure Boot: Andrea Barisani - Head of Hardware Security
42 pages
Instruction For Qualcomm Hs-Usb Qdloader 9008
No ratings yet
Instruction For Qualcomm Hs-Usb Qdloader 9008
5 pages
Informix 4gl Reference Guide
No ratings yet
Informix 4gl Reference Guide
1,312 pages
Linux Kernel Programming: A comprehensive and practical guide to kernel internals, writing modules, and kernel synchronization
From Everand
Linux Kernel Programming: A comprehensive and practical guide to kernel internals, writing modules, and kernel synchronization
Kaiwan N. Billimoria
No ratings yet
CS Students Linux User's Guide: Writing A Makefile
No ratings yet
CS Students Linux User's Guide: Writing A Makefile
7 pages
Run Os X Mavericks 10.9
No ratings yet
Run Os X Mavericks 10.9
29 pages
Windows 7 Unattended
No ratings yet
Windows 7 Unattended
24 pages
Tinaware Launchpad
100% (1)
Tinaware Launchpad
11 pages
Asio SDK 2.3
No ratings yet
Asio SDK 2.3
50 pages
Ceronix Tech Training 050107
No ratings yet
Ceronix Tech Training 050107
60 pages
UCD Linux Security Checklist
100% (1)
UCD Linux Security Checklist
5 pages
Setup L2TP - IPsec VPN Server On SoftEther VPN Server - SoftEther VPN Project
No ratings yet
Setup L2TP - IPsec VPN Server On SoftEther VPN Server - SoftEther VPN Project
4 pages
Hiding Windows 7 Completely - DONE (New Video Added 22 8)
No ratings yet
Hiding Windows 7 Completely - DONE (New Video Added 22 8)
15 pages
Linux Slackware Installation Guide
No ratings yet
Linux Slackware Installation Guide
26 pages
Game Boy CPU Manual
No ratings yet
Game Boy CPU Manual
139 pages
Devids
No ratings yet
Devids
11 pages
CONFIG - USR1 Parameter Descriptions
No ratings yet
CONFIG - USR1 Parameter Descriptions
8 pages
FactoryDownload User Guide (En)
No ratings yet
FactoryDownload User Guide (En)
19 pages
80096503-001-E ID TECH SecureMag OPOS User's Manual
No ratings yet
80096503-001-E ID TECH SecureMag OPOS User's Manual
34 pages
N4 Setup With Virtual DJ LE PDF
No ratings yet
N4 Setup With Virtual DJ LE PDF
4 pages
Rpi Camera Guide
No ratings yet
Rpi Camera Guide
60 pages
Forensic Disk Imaging Step-By-Step
100% (2)
Forensic Disk Imaging Step-By-Step
4 pages
Omap U Boot Utils Refman
No ratings yet
Omap U Boot Utils Refman
72 pages
7 GUID Partition Table (GPT) PDF
100% (1)
7 GUID Partition Table (GPT) PDF
4 pages
Informix Administrator Guide
No ratings yet
Informix Administrator Guide
138 pages
fdg2014 Paper 20 PDF
No ratings yet
fdg2014 Paper 20 PDF
8 pages
LF Pub History Embedded Linux
No ratings yet
LF Pub History Embedded Linux
21 pages
Embedded Linux System Development Training Lab Book
No ratings yet
Embedded Linux System Development Training Lab Book
4 pages
TheSecretSocietiesofAllAgesandCountries 10016510
No ratings yet
TheSecretSocietiesofAllAgesandCountries 10016510
385 pages
Install & Setup Android Studio Java JDK & SDK
No ratings yet
Install & Setup Android Studio Java JDK & SDK
9 pages
TV VCR Prod List
No ratings yet
TV VCR Prod List
73 pages
The DB9-USB Family of UART Converter Modules: Datasheet
No ratings yet
The DB9-USB Family of UART Converter Modules: Datasheet
26 pages
AVGuide SF Cremona M
No ratings yet
AVGuide SF Cremona M
3 pages
Chip Siemens Sle4442 Developed Manual
No ratings yet
Chip Siemens Sle4442 Developed Manual
35 pages
Instructions For Android 10.0
0% (1)
Instructions For Android 10.0
13 pages
Open Ocd
No ratings yet
Open Ocd
137 pages
SCO Open Server 5.0.7 HandBook
No ratings yet
SCO Open Server 5.0.7 HandBook
446 pages
OS Lab
No ratings yet
OS Lab
130 pages
Service Manual For The 55LTV (LED)
No ratings yet
Service Manual For The 55LTV (LED)
26 pages
eyeOS User Manual
100% (4)
eyeOS User Manual
26 pages
Arm Linux Ts72xx
No ratings yet
Arm Linux Ts72xx
49 pages
Win32 Error Codes PDF
No ratings yet
Win32 Error Codes PDF
31 pages
CashCode MVU Manual
No ratings yet
CashCode MVU Manual
33 pages
Cross Toolchain For ARM
No ratings yet
Cross Toolchain For ARM
13 pages
LCD TV Philips 32hfl3331-93 Tcm3.1ala
No ratings yet
LCD TV Philips 32hfl3331-93 Tcm3.1ala
72 pages
RTOS Specification
No ratings yet
RTOS Specification
15 pages
Standard Accessories: Install Software and Driver
No ratings yet
Standard Accessories: Install Software and Driver
4 pages
Query Optimization
100% (1)
Query Optimization
138 pages
USB Firmware Update Instruction Manual: AVR-X3400H
No ratings yet
USB Firmware Update Instruction Manual: AVR-X3400H
1 page
Special Edition Using Visual C++ 6.0
No ratings yet
Special Edition Using Visual C++ 6.0
464 pages
ISQL
No ratings yet
ISQL
5 pages
ID-003 To Pulse Converter: General Description
No ratings yet
ID-003 To Pulse Converter: General Description
3 pages
Serato DJ Intro 1.2.6 Software Manual - English
No ratings yet
Serato DJ Intro 1.2.6 Software Manual - English
36 pages
PC Interfacing Pocket Reference
From Everand
PC Interfacing Pocket Reference
Myke Predko
No ratings yet
Oracle VM Manager 2.1.2
From Everand
Oracle VM Manager 2.1.2
Tarry Singh
No ratings yet
Building Telephony Systems with OpenSER
From Everand
Building Telephony Systems with OpenSER
Goncalves Flavio E.
No ratings yet
Windows Server 2008 For Dummies
From Everand
Windows Server 2008 For Dummies
Ed Tittel
No ratings yet
ARM Processor - Instruction Set - Module 5
No ratings yet
ARM Processor - Instruction Set - Module 5
24 pages
CS 301 Genrica W
No ratings yet
CS 301 Genrica W
31 pages
CS6501 IP Lecture Notes
No ratings yet
CS6501 IP Lecture Notes
106 pages
8085 Project Report
100% (1)
8085 Project Report
20 pages
MindConnect IoT2040 Product Sheet v1.0
No ratings yet
MindConnect IoT2040 Product Sheet v1.0
5 pages
Technical Documentation
No ratings yet
Technical Documentation
4 pages
Environmental Data Acquisition System: Air Quality Monitoring Systems
No ratings yet
Environmental Data Acquisition System: Air Quality Monitoring Systems
2 pages
all.preinstalled-system-common.apps.on.vanillaOSafter.Windex
0% (1)
all.preinstalled-system-common.apps.on.vanillaOSafter.Windex
4 pages
Afterlock
100% (1)
Afterlock
33 pages
Easyctf Writeups
No ratings yet
Easyctf Writeups
64 pages
Sony Vaio FE880E Foxconn MS13 MBX 149
No ratings yet
Sony Vaio FE880E Foxconn MS13 MBX 149
67 pages
Machine TV Interface: Memory Processor
No ratings yet
Machine TV Interface: Memory Processor
2 pages
MaaS360 Overview
No ratings yet
MaaS360 Overview
29 pages
Design Pro User's Manual
0% (1)
Design Pro User's Manual
378 pages
A129 Manual
No ratings yet
A129 Manual
14 pages
Microsoft Corporation SM
No ratings yet
Microsoft Corporation SM
18 pages
Synopsis Major
No ratings yet
Synopsis Major
4 pages
RTUtil560 Users Guide R8
No ratings yet
RTUtil560 Users Guide R8
101 pages
Concept of Programming
No ratings yet
Concept of Programming
7 pages
Sol 2.1 Custom Config Changes
No ratings yet
Sol 2.1 Custom Config Changes
7 pages
18 Impressive Computer Shortcuts and Tricks
No ratings yet
18 Impressive Computer Shortcuts and Tricks
8 pages
Catalog Siemens Detectie
No ratings yet
Catalog Siemens Detectie
340 pages
Z-002 Zigbee Module: H-2 Technik Ug (Haftungsbescgränkt)
No ratings yet
Z-002 Zigbee Module: H-2 Technik Ug (Haftungsbescgränkt)
17 pages
Quick Install Connectbox CBv2+ V3.0 en-GB
No ratings yet
Quick Install Connectbox CBv2+ V3.0 en-GB
8 pages
Storage Classes in C
No ratings yet
Storage Classes in C
6 pages
Tutorial
No ratings yet
Tutorial
38 pages
Solid Principles Succinctly
No ratings yet
Solid Principles Succinctly
80 pages
Applying GOF Design Patterns: Applying UML and Patterns Craig Larman Presented By: Naga Venkata Neelam
No ratings yet
Applying GOF Design Patterns: Applying UML and Patterns Craig Larman Presented By: Naga Venkata Neelam
65 pages
Book of Programming Problems
No ratings yet
Book of Programming Problems
12 pages
LA-D993P Rev 1.0 Schematic Diagram
No ratings yet
LA-D993P Rev 1.0 Schematic Diagram
70 pages