INFORMIX- 4GL

Reference Manual
Versi on 7.3
Jul y 1999
Part No. 000- 5299
ii INFORMIX- 4GL Reference Manual
Published by INFORMIX

Press Informix Corporation

4100 Bohannon Drive
Menlo Park, CA 94025-1032
1999 Informix Corporation. All rights reserved. The following are trademarks of Informix Corporation or its
afliates:
Answers OnLine
TM
; CBT Store
TM
; C-ISAM

; Client SDK
TM
; ContentBase
TM
; Cyber Planet
TM
; DataBlade

; Data
Director
TM
; Decision Frontier
TM
; Dynamic Scalable Architecture
TM
; Dynamic Server
TM
; Dynamic Server
TM
,
Developer Edition
TM
; Dynamic Server
TM
with Advanced Decision Support Option
TM
; Dynamic Server
TM
with
Extended Parallel Option
TM
; Dynamic Server
TM
with MetaCube

ROLAP Option; Dynamic Server

TM
with
Universal Data Option
TM
; Dynamic Server
TM
with Web Integration Option
TM
; Dynamic Server
TM
, Workgroup
Edition
TM
; FastStart
TM
; 4GL for ToolBus
TM
; If you can imagine it, you can manage it
SM
; Illustra

; INFORMIX

;
Informix Data Warehouse Solutions... Turning Data Into Business Advantage
TM
; INFORMIX

-Enterprise
Gateway with DRDA

; Informix Enterprise Merchant

TM
; INFORMIX

-4GL; Informix-JWorks
TM
; InformixLink

;
Informix Session Proxy
TM
; InfoShelf
TM
; Interforum
TM
; I-SPY
TM
; Mediazation
TM
; MetaCube

; NewEra
TM
;
ON-Bar
TM
; OnLine Dynamic Server
TM
; OnLine for NetWare

; OnLine/Secure Dynamic Server

TM
; OpenCase

;
ORCA
TM
; Regency Support

; Solution Design Labs

SM
; Solution Design Program
SM
; SuperView

; Universal
Database Components
TM
; Universal Web Connect
TM
; ViewPoint

; Visionary
TM
; Web Integration Suite
TM
. The
Informix logo is registered with the United States Patent and Trademark Ofce. The DataBlade logo is
registered with the United States Patent and Trademark Ofce.
Documentation Team: Tom Houston, Adam Barnett, Mary Leigh Burke, Evelyn Eldridge,
Barbara Nomiyama, Elaina Von Haas, Eileen Wollam
Contributors: Jonathan Lefer, Sudhakar Prabhu, Alan Denney
GOVERNMENT LICENSE RIGHTS
Software and documentation acquired by or for the US Government are provided with rights as follows:
(1) if for civilian agency use, with rights as restrictedby vendors standardlicense, as prescribedin FAR12.212;
(2) if for Dept. of Defense use, with rights as restricted by vendors standard license, unless superseded by a
negotiated vendor license, as prescribed in DFARS 227.7202. Any whole or partial reproduction of software or
documentation marked with this legend must reproduce this legend.
Table of Contents
Table of
Contents
Introduction
In This Introduction . . . . . . . . . . . . . . . . . 3
About This Manual . . . . . . . . . . . . . . . . . . 3
Organization of This Manual . . . . . . . . . . . . . 3
Types of Readers . . . . . . . . . . . . . . . . . 5
Software Dependencies . . . . . . . . . . . . . . . 5
Assumptions About Your Locale. . . . . . . . . . . . 6
Demonstration Database and Examples . . . . . . . . . 6
Accessing Databases from Within 4GL. . . . . . . . . . 7
Documentation Conventions . . . . . . . . . . . . . . 8
Typographical Conventions . . . . . . . . . . . . . 8
Icon Conventions . . . . . . . . . . . . . . . . . 9
Example-Code Conventions . . . . . . . . . . . . . 10
Syntax Conventions . . . . . . . . . . . . . . . . 10
Additional Documentation . . . . . . . . . . . . . . . 15
Documentation Included with 4GL . . . . . . . . . . . 15
On-Line Manuals . . . . . . . . . . . . . . . . . 16
On-Line Help . . . . . . . . . . . . . . . . . . 16
On-Line Error Messages. . . . . . . . . . . . . . . 16
Related Reading . . . . . . . . . . . . . . . . . 18
Informix Developer Network . . . . . . . . . . . . . 18
Informix Welcomes Your Comments . . . . . . . . . . . . 19
Chapter 1 Compiling INFORMIX-4GL Source Files
In This Chapter . . . . . . . . . . . . . . . . . . . 1-3
Two Implementations of INFORMIX-4GL . . . . . . . . . . 1-3
Differences Between the C Compiler and RDS Versions . . . . 1-4
The C Compiler Version . . . . . . . . . . . . . . . . 1-6
The Five-Phase 4GL Compilation Process. . . . . . . . . 1-6
The Programmers Environment . . . . . . . . . . . . 1-8
iv INFORMIX- 4GL Reference Manual
Creating Programs in the Programmers Environment . . . . 1-26
Creating Programs at the Command Line . . . . . . . . 1-32
Program Filename Extensions . . . . . . . . . . . . 1-45
The Rapid Development System . . . . . . . . . . . . . 1-47
The Programmers Environment . . . . . . . . . . . 1-47
Creating Programs in the Programmers Environment . . . . 1-67
Creating Programs at the Command Line . . . . . . . . 1-72
Program Filename Extensions . . . . . . . . . . . . 1-86
Chapter 2 The INFORMIX-4GL Language
In This Chapter . . . . . . . . . . . . . . . . . . . 2-3
Language Features . . . . . . . . . . . . . . . . . 2-3
Lettercase Insensitivity. . . . . . . . . . . . . . . 2-3
Whitespace, Quotation Marks, Escape Symbols,
and Delimiters . . . . . . . . . . . . . . 2-4
Character Set . . . . . . . . . . . . . . . . . . 2-5
4GL Statements . . . . . . . . . . . . . . . . . 2-5
Comments . . . . . . . . . . . . . . . . . . . 2-8
Source-Code Modules and Program Blocks. . . . . . . . 2-10
Statement Blocks . . . . . . . . . . . . . . . . . 2-12
Statement Segments . . . . . . . . . . . . . . . . 2-13
4GL Identiers . . . . . . . . . . . . . . . . . 2-14
Interacting with Users . . . . . . . . . . . . . . . . 2-22
Ring Menus . . . . . . . . . . . . . . . . . . 2-22
Screen Forms . . . . . . . . . . . . . . . . . . 2-25
4GL Windows . . . . . . . . . . . . . . . . . . 2-28
On-Line Help . . . . . . . . . . . . . . . . . . 2-29
Nested and Recursive Statements . . . . . . . . . . . 2-31
Exception Handling . . . . . . . . . . . . . . . . . 2-39
Compile-Time Errors and Warnings . . . . . . . . . . 2-39
Runtime Errors and Warnings . . . . . . . . . . . . 2-39
Changes to 4GL Error Handling . . . . . . . . . . . 2-43
Error Handling with SQLCA . . . . . . . . . . . . 2-44
Chapter 3 Data Types and Expressions
In This Chapter . . . . . . . . . . . . . . . . . . . 3-5
Data Values in 4GL Programs . . . . . . . . . . . . . . 3-5
Data Types of 4GL . . . . . . . . . . . . . . . . . . 3-6
Simple Data Types . . . . . . . . . . . . . . . . 3-9
Structured Data Types . . . . . . . . . . . . . . . 3-12
Tabl e of Contents v
Large Data Types . . . . . . . . . . . . . . . . 3-12
Descriptions of the 4GL Data Types . . . . . . . . . . 3-12
ARRAY . . . . . . . . . . . . . . . . . . . 3-13
BYTE . . . . . . . . . . . . . . . . . . . . 3-14
CHAR . . . . . . . . . . . . . . . . . . . . 3-15
CHARACTER . . . . . . . . . . . . . . . . . 3-17
DATE . . . . . . . . . . . . . . . . . . . . 3-17
DATETIME . . . . . . . . . . . . . . . . . . 3-18
DEC. . . . . . . . . . . . . . . . . . . . . 3-23
DECIMAL (p, s). . . . . . . . . . . . . . . . . 3-23
DECIMAL (p) . . . . . . . . . . . . . . . . . 3-24
DOUBLE PRECISION . . . . . . . . . . . . . . 3-25
FLOAT. . . . . . . . . . . . . . . . . . . . 3-25
INT . . . . . . . . . . . . . . . . . . . . . 3-26
INTEGER . . . . . . . . . . . . . . . . . . . 3-26
INTERVAL . . . . . . . . . . . . . . . . . . 3-27
MONEY . . . . . . . . . . . . . . . . . . . 3-32
NUMERIC . . . . . . . . . . . . . . . . . . 3-33
REAL . . . . . . . . . . . . . . . . . . . . 3-33
RECORD . . . . . . . . . . . . . . . . . . . 3-34
SMALLFLOAT . . . . . . . . . . . . . . . . . 3-36
SMALLINT . . . . . . . . . . . . . . . . . . 3-37
TEXT . . . . . . . . . . . . . . . . . . . . 3-38
VARCHAR . . . . . . . . . . . . . . . . . . 3-39
Data Type Conversion . . . . . . . . . . . . . . 3-41
Summary of Compatible 4GL Data Types . . . . . . . . 3-45
Expressions of 4GL . . . . . . . . . . . . . . . 3-49
Differences Between 4GL and SQL Expressions . . . . . . 3-50
Components of 4GL Expressions . . . . . . . . . . . 3-52
Boolean Expressions . . . . . . . . . . . . . . . 3-60
Integer Expressions . . . . . . . . . . . . . . . 3-63
Number Expressions . . . . . . . . . . . . . . . 3-66
Character Expressions . . . . . . . . . . . . . . 3-68
Time Expressions . . . . . . . . . . . . . . . . 3-72
Field Clause . . . . . . . . . . . . . . . . . . 3-87
Table Qualiers . . . . . . . . . . . . . . . . . 3-90
THRU or THROUGH Keywords and .* Notation . . . . . 3-93
ATTRIBUTE Clause . . . . . . . . . . . . . . . 3-97
vi INFORMIX- 4GL Reference Manual
Chapter 4 INFORMIX-4GL Statements
In This Chapter . . . . . . . . . . . . . . . . . . . 4-9
The 4GL Statement Set . . . . . . . . . . . . . . . . 4-9
Types of SQL Statements . . . . . . . . . . . . . . 4-10
Other Types of 4GL Statements . . . . . . . . . . . . 4-13
Statement Descriptions . . . . . . . . . . . . . . . . 4-15
CALL. . . . . . . . . . . . . . . . . . . . . 4-16
CASE . . . . . . . . . . . . . . . . . . . . . 4-22
CLEAR . . . . . . . . . . . . . . . . . . . . 4-28
CLOSE FORM. . . . . . . . . . . . . . . . . . 4-31
CLOSE WINDOW . . . . . . . . . . . . . . . . 4-33
CONSTRUCT . . . . . . . . . . . . . . . . . . 4-35
CONTINUE . . . . . . . . . . . . . . . . . . 4-68
CURRENT WINDOW . . . . . . . . . . . . . . . 4-70
DATABASE. . . . . . . . . . . . . . . . . . . 4-73
DEFER . . . . . . . . . . . . . . . . . . . . 4-80
DEFINE . . . . . . . . . . . . . . . . . . . . 4-83
DISPLAY . . . . . . . . . . . . . . . . . . . 4-93
DISPLAY ARRAY . . . . . . . . . . . . . . . . 4-105
DISPLAY FORM . . . . . . . . . . . . . . . . . 4-116
END . . . . . . . . . . . . . . . . . . . . . 4-119
ERROR . . . . . . . . . . . . . . . . . . . . 4-121
EXIT . . . . . . . . . . . . . . . . . . . . . 4-124
FINISH REPORT . . . . . . . . . . . . . . . . . 4-128
FOR . . . . . . . . . . . . . . . . . . . . . 4-131
FOREACH . . . . . . . . . . . . . . . . . . . 4-134
FUNCTION . . . . . . . . . . . . . . . . . . 4-143
GLOBALS . . . . . . . . . . . . . . . . . . . 4-149
GOTO . . . . . . . . . . . . . . . . . . . . 4-155
IF . . . . . . . . . . . . . . . . . . . . . . 4-158
INITIALIZE . . . . . . . . . . . . . . . . . . 4-160
INPUT . . . . . . . . . . . . . . . . . . . . 4-164
INPUT ARRAY . . . . . . . . . . . . . . . . . 4-190
LABEL . . . . . . . . . . . . . . . . . . . . 4-227
LET . . . . . . . . . . . . . . . . . . . . . 4-229
LOAD . . . . . . . . . . . . . . . . . . . . 4-233
LOCATE. . . . . . . . . . . . . . . . . . . . 4-242
MAIN . . . . . . . . . . . . . . . . . . . . 4-247
MENU . . . . . . . . . . . . . . . . . . . . 4-250
MESSAGE . . . . . . . . . . . . . . . . . . . 4-275
NEED. . . . . . . . . . . . . . . . . . . . . 4-278
OPEN FORM . . . . . . . . . . . . . . . . . . 4-279
Tabl e of Contents vii
OPEN WINDOW . . . . . . . . . . . . . . . . 4-281
OPTIONS . . . . . . . . . . . . . . . . . . . 4-293
OUTPUT TO REPORT . . . . . . . . . . . . . . 4-310
PAUSE . . . . . . . . . . . . . . . . . . . . 4-313
PREPARE . . . . . . . . . . . . . . . . . . . 4-314
PRINT . . . . . . . . . . . . . . . . . . . . 4-326
PROMPT . . . . . . . . . . . . . . . . . . . 4-327
REPORT . . . . . . . . . . . . . . . . . . . 4-334
RETURN . . . . . . . . . . . . . . . . . . . 4-339
RUN . . . . . . . . . . . . . . . . . . . . 4-342
SCROLL . . . . . . . . . . . . . . . . . . . 4-346
SKIP . . . . . . . . . . . . . . . . . . . . 4-348
SLEEP . . . . . . . . . . . . . . . . . . . . 4-350
SQL . . . . . . . . . . . . . . . . . . . . . 4-351
START REPORT . . . . . . . . . . . . . . . . 4-356
TERMINATE REPORT . . . . . . . . . . . . . . 4-365
UNLOAD. . . . . . . . . . . . . . . . . . . 4-368
VALIDATE . . . . . . . . . . . . . . . . . . 4-373
WHENEVER. . . . . . . . . . . . . . . . . . 4-377
WHILE. . . . . . . . . . . . . . . . . . . . 4-383
Chapter 5 Built-In Functions and Operators
In This Chapter . . . . . . . . . . . . . . . . . . 5-5
Functions in 4GL Programs . . . . . . . . . . . . . . 5-5
Built-In 4GL Functions . . . . . . . . . . . . . . 5-6
Built-In and External SQL Functions and Procedures . . . . 5-7
C Functions . . . . . . . . . . . . . . . . . . 5-7
ESQL/C Functions . . . . . . . . . . . . . . . 5-7
Programmer-Dened 4GL Functions . . . . . . . . . 5-8
Invoking Functions . . . . . . . . . . . . . . . 5-9
Operators of 4GL . . . . . . . . . . . . . . . . . 5-11
Built-In Functions of Informix Dynamic 4GL . . . . . . . . 5-12
Syntax of Built-In Functions and Operators . . . . . . . . 5-13
Aggregate Report Functions . . . . . . . . . . . . 5-14
ARG_VAL( ) . . . . . . . . . . . . . . . . . . 5-18
Arithmetic Operators . . . . . . . . . . . . . . . 5-20
ARR_COUNT( ) . . . . . . . . . . . . . . . . 5-27
ARR_CURR( ) . . . . . . . . . . . . . . . . . 5-29
ASCII . . . . . . . . . . . . . . . . . . . . 5-31
Boolean Operators . . . . . . . . . . . . . . . . 5-33
CLIPPED . . . . . . . . . . . . . . . . . . . 5-44
COLUMN . . . . . . . . . . . . . . . . . . 5-46
viii INFORMIX- 4GL Reference Manual
Concatenation ( || ) Operator . . . . . . . . . . . . 5-49
CURRENT . . . . . . . . . . . . . . . . . . . 5-50
CURSOR_NAME( ) . . . . . . . . . . . . . . . . 5-52
DATE. . . . . . . . . . . . . . . . . . . . . 5-55
DAY( ) . . . . . . . . . . . . . . . . . . . . 5-58
DOWNSHIFT( ) . . . . . . . . . . . . . . . . . 5-59
ERR_GET( ) . . . . . . . . . . . . . . . . . . 5-60
ERR_PRINT( ) . . . . . . . . . . . . . . . . . 5-61
ERR_QUIT( ) . . . . . . . . . . . . . . . . . . 5-62
ERRORLOG( ) . . . . . . . . . . . . . . . . . . 5-63
EXTEND( ) . . . . . . . . . . . . . . . . . . . 5-65
FGL_DRAWBOX( ) . . . . . . . . . . . . . . . . 5-68
FGL_GETENV( ) . . . . . . . . . . . . . . . . . 5-70
FGL_GETKEY( ) . . . . . . . . . . . . . . . . . 5-72
FGL_KEYVAL( ) . . . . . . . . . . . . . . . . . 5-73
FGL_LASTKEY( ) . . . . . . . . . . . . . . . . 5-75
FGL_SCR_SIZE( ) . . . . . . . . . . . . . . . . 5-77
FIELD_TOUCHED( ) . . . . . . . . . . . . . . . 5-79
GET_FLDBUF( ) . . . . . . . . . . . . . . . . . 5-82
INFIELD( ) . . . . . . . . . . . . . . . . . . . 5-85
LENGTH( ) . . . . . . . . . . . . . . . . . . 5-87
LINENO. . . . . . . . . . . . . . . . . . . . 5-89
MDY( ) . . . . . . . . . . . . . . . . . . . . 5-90
Membership ( . ) Operator. . . . . . . . . . . . . . 5-91
MONTH( ) . . . . . . . . . . . . . . . . . . . 5-92
NUM_ARGS( ) . . . . . . . . . . . . . . . . . 5-93
ORD( ) . . . . . . . . . . . . . . . . . . . . 5-94
PAGENO . . . . . . . . . . . . . . . . . . . 5-95
SCR_LINE( ) . . . . . . . . . . . . . . . . . . 5-96
SET_COUNT( ) . . . . . . . . . . . . . . . . . 5-98
SHOWHELP( ) . . . . . . . . . . . . . . . . . 5-100
SPACE . . . . . . . . . . . . . . . . . . . . 5-102
STARTLOG( ) . . . . . . . . . . . . . . . . . . 5-103
Substring ( [ ] ) Operator . . . . . . . . . . . . . . 5-106
TIME . . . . . . . . . . . . . . . . . . . . 5-108
TODAY . . . . . . . . . . . . . . . . . . . . 5-110
UNITS . . . . . . . . . . . . . . . . . . . . 5-111
UPSHIFT( ) . . . . . . . . . . . . . . . . . . . 5-113
USING . . . . . . . . . . . . . . . . . . . . 5-115
WEEKDAY( ) . . . . . . . . . . . . . . . . . . 5-125
WORDWRAP . . . . . . . . . . . . . . . . . . 5-128
YEAR( ) . . . . . . . . . . . . . . . . . . . . 5-131
Tabl e of Contents ix
Chapter 6 Screen Forms
In This Chapter . . . . . . . . . . . . . . . . . . 6-5
4GL Forms . . . . . . . . . . . . . . . . . . . . 6-5
Form Drivers . . . . . . . . . . . . . . . . . 6-5
Form Fields . . . . . . . . . . . . . . . . . . 6-7
Structure of a Form Specication File . . . . . . . . . . . 6-9
DATABASE Section . . . . . . . . . . . . . . . . . 6-12
Database References in the DATABASE Section. . . . . . 6-13
The FORMONLY Option . . . . . . . . . . . . . 6-13
The WITHOUT NULL INPUT Option . . . . . . . . . 6-14
SCREEN Section . . . . . . . . . . . . . . . . . . 6-15
The SIZE Option . . . . . . . . . . . . . . . . 6-15
The Screen Layout . . . . . . . . . . . . . . . . 6-17
Display Fields . . . . . . . . . . . . . . . . . 6-17
Literal Characters in Forms. . . . . . . . . . . . . 6-19
TABLES Section . . . . . . . . . . . . . . . . . . 6-23
Table Aliases . . . . . . . . . . . . . . . . . . 6-24
ATTRIBUTES Section . . . . . . . . . . . . . . . . 6-25
FORMONLY Fields . . . . . . . . . . . . . . . 6-29
Multiple-Segment Fields . . . . . . . . . . . . . 6-31
Field Attributes . . . . . . . . . . . . . . . . 6-32
Field Attribute Syntax . . . . . . . . . . . . . . 6-34
AUTONEXT . . . . . . . . . . . . . . . . . . 6-35
CENTURY . . . . . . . . . . . . . . . . . . 6-36
COLOR . . . . . . . . . . . . . . . . . . . 6-38
COMMENTS . . . . . . . . . . . . . . . . . 6-44
DEFAULT . . . . . . . . . . . . . . . . . . 6-46
DISPLAY LIKE . . . . . . . . . . . . . . . . . 6-49
DOWNSHIFT . . . . . . . . . . . . . . . . . 6-50
FORMAT . . . . . . . . . . . . . . . . . . . 6-51
INCLUDE . . . . . . . . . . . . . . . . . . 6-54
INVISIBLE . . . . . . . . . . . . . . . . . . 6-57
NOENTRY . . . . . . . . . . . . . . . . . . 6-58
PICTURE . . . . . . . . . . . . . . . . . . . 6-59
PROGRAM . . . . . . . . . . . . . . . . . . 6-61
REQUIRED . . . . . . . . . . . . . . . . . . 6-63
REVERSE . . . . . . . . . . . . . . . . . . . 6-64
UPSHIFT . . . . . . . . . . . . . . . . . . . 6-65
VALIDATE LIKE . . . . . . . . . . . . . . . . 6-66
VERIFY . . . . . . . . . . . . . . . . . . . 6-67
WORDWRAP . . . . . . . . . . . . . . . . . 6-68
x INFORMIX- 4GL Reference Manual
INSTRUCTIONS Section . . . . . . . . . . . . . . . 6-74
Screen Records . . . . . . . . . . . . . . . . . 6-74
Screen Arrays . . . . . . . . . . . . . . . . . . 6-77
Field Delimiters . . . . . . . . . . . . . . . . . 6-79
Default Attributes . . . . . . . . . . . . . . . . . . 6-81
Precedence of Field Attribute Specications . . . . . . . 6-84
Default Attributes in an ANSI-Compliant Database . . . . . 6-84
Creating and Compiling a Form . . . . . . . . . . . . . 6-85
Compiling a Form Through the Programmers
Environment . . . . . . . . . . . . . . . 6-85
Compiling a Form at the Command Line . . . . . . . . 6-88
Default Forms . . . . . . . . . . . . . . . . . . 6-89
Using PERFORM Forms in 4GL . . . . . . . . . . . . . 6-92
Chapter 7 INFORMIX-4GL Reports
In This Chapter . . . . . . . . . . . . . . . . . . . 7-3
Features of 4GL Reports . . . . . . . . . . . . . . . . 7-4
Producing 4GL Reports . . . . . . . . . . . . . . . . 7-5
The Report Driver . . . . . . . . . . . . . . . . 7-5
The Report Denition . . . . . . . . . . . . . . . 7-7
DEFINE Section . . . . . . . . . . . . . . . . . . 7-10
OUTPUT Section . . . . . . . . . . . . . . . . . . 7-12
ORDER BY Section . . . . . . . . . . . . . . . . . 7-23
FORMAT Section . . . . . . . . . . . . . . . . . . 7-28
FORMAT Section Control Blocks . . . . . . . . . . . . 7-32
AFTER GROUP OF . . . . . . . . . . . . . . . . 7-34
BEFORE GROUP OF . . . . . . . . . . . . . . . 7-37
FIRST PAGE HEADER. . . . . . . . . . . . . . . 7-40
ON EVERY ROW. . . . . . . . . . . . . . . . . 7-42
ON LAST ROW . . . . . . . . . . . . . . . . . 7-44
PAGE HEADER . . . . . . . . . . . . . . . . . 7-45
PAGE TRAILER . . . . . . . . . . . . . . . . . 7-47
Statements in REPORT Control Blocks . . . . . . . . . . 7-48
Statements Valid Only in the FORMAT Section . . . . . . 7-49
EXIT REPORT . . . . . . . . . . . . . . . . . . 7-50
NEED. . . . . . . . . . . . . . . . . . . . . 7-51
PAUSE . . . . . . . . . . . . . . . . . . . . 7-52
PRINT . . . . . . . . . . . . . . . . . . . . 7-53
SKIP . . . . . . . . . . . . . . . . . . . . . 7-66
Tabl e of Contents xi
Appendix A The ASCII Character Set
Appendix B INFORMIX-4GL Utility Programs
Appendix C Using C with INFORMIX-4GL
Appendix D Environment Variables
Appendix E Developing Applications with Global Language Support
Appendix F Modifying termcap and terminfo
Appendix G Reserved Words
Appendix H The Demonstration Application
Appendix I SQL Statements That Can Be Embedded in 4GL Code
Glossary
Index
xii INFORMIX- 4GL Reference Manual
Introduction
Introduction
In This Introduction . . . . . . . . . . . . . . . . . . 3
About This Manual . . . . . . . . . . . . . . . . . . . 3
Organization of This Manual . . . . . . . . . . . . . . 3
Types of Readers . . . . . . . . . . . . . . . . . . 5
Software Dependencies . . . . . . . . . . . . . . . . 5
Assumptions About Your Locale. . . . . . . . . . . . . 6
Demonstration Database and Examples . . . . . . . . . . 6
Accessing Databases from Within 4GL. . . . . . . . . . . 7
Documentation Conventions . . . . . . . . . . . . . . . 8
Typographical Conventions . . . . . . . . . . . . . . 8
Icon Conventions . . . . . . . . . . . . . . . . . . 9
Feature, Product, and Platform Icons . . . . . . . . . . 9
Compliance Icons . . . . . . . . . . . . . . . . 9
Example-Code Conventions . . . . . . . . . . . . . . 10
Syntax Conventions . . . . . . . . . . . . . . . . . 10
Elements That Can Appear on the Path . . . . . . . . . 11
How to Read a Syntax Diagram. . . . . . . . . . . . 13
Additional Documentation . . . . . . . . . . . . . . . . 15
Documentation Included with 4GL . . . . . . . . . . . . 15
On-Line Manuals . . . . . . . . . . . . . . . . . . 16
On-Line Help . . . . . . . . . . . . . . . . . . . 16
On-Line Error Messages. . . . . . . . . . . . . . . . 16
Related Reading . . . . . . . . . . . . . . . . . . 18
Informix Developer Network . . . . . . . . . . . . . . 18
Informix Welcomes Your Comments . . . . . . . . . . . . . 19
2 INFORMIX- 4GL Reference Manual
Introducti on 3
In This Introduction
This Introduction provides an overview of the information in this manual
and describes the conventions it uses.
About This Manual
This manual is designed to be a day-to-day, keyboard-side companion for
4GL programmers. It describes the features and syntax of the 4GL language,
including 4GL statements, forms, reports, and the built-in functions and
operators.
Organization of This Manual
This manual is dividedinto two volumes andincludes the following chapters
and appendixes:
B Chapter 1, Compiling INFORMIX-4GL Source Files, describes the
C Compiler and Rapid Development System implementations of
INFORMIX-4GL. It also explains howto create executable versions of
4GL source les, both fromthe Programmers Environment andfrom
the command line.
B Chapter 2, The INFORMIX-4GL Language, provides an overview
of 4GL language features and graphical features of the applications
that you can create with INFORMIX-4GL.
B Chapter 3, Data Types and Expressions, describes 4GL data types,
expressions, and other syntax topics that affect several statements.
4 INFORMIX- 4GL Reference Manual
Organi zati on of Thi s Manual
B Chapter 4, INFORMIX-4GL Statements, describes the statements
of 4GL in alphabetical order.
B Chapter 5, Built-In Functions andOperators, includes an overview
of the predened functions and operators of 4GL, and describes their
individual syntax, with examples of usage.
B Chapter 6, Screen Forms, provides an overview of 4GL screen
forms and form drivers, and describes the syntax of 4GL form speci-
cation les. It also describes how to create forms with the form4gl
form compiler, and how the upscol utility can set default attributes.
B Chapter 7, INFORMIX-4GL Reports, offers an overview of 4GL
reports and report drivers, and describes the syntax of 4GL report
denitions. It also describes the syntax of statements and operators
that can appear only in 4GL reports.
B Appendix A, The ASCII Character Set, lists the ASCII characters
and their numeric codes.
B Appendix B, INFORMIX-4GL Utility Programs, describes the
mkmessage and upscol utility programs.
B Appendix C, Using C with INFORMIX-4GL, describes howto call
C functions from4GL programs, and vice versa, and describes a
function library for conversion between the DECIMAL data type of
4GL and the C data types.
B Appendix D, Environment Variables, describes the environment
variables that are used by 4GL.
B Appendix E, Developing Applications with Global Language
Support, describes the internationalization and localization
features that are provided with 4GL, and shows howto develop 4GL
applications that are world-ready and easy to localize.
B Appendix F, Modifying termcap and terminfo, describes the
modications you can make to your termcap and terminfo les to
extend function key denitions, to specify characters for window
borders, and to enable 4GL programs to interact with terminals that
support color displays.
B Appendix G, Reserved Words, lists words that you should not
declare as identiers in 4GL programs. It also lists the ANSI reserved
words of SQL.
B Appendix H, The Demonstration Application, lists the code of the
demo4.4ge demonstration application.
Introducti on 5
Types of Readers
B Appendix I, SQL Statements That Can Be Embedded in 4GL Code,
lists SQL syntax that is directly supported in 4GL.
B The Glossary denes terms used in the 4GL documentation set.
Types of Readers
This manual is written for all 4GL developers. You do not need database
management experience nor familiarity with relational database concepts to
use this manual. A knowledge of SQL (structured query language), however,
and experience using a high-level programming language would be useful.
Software Dependencies
This manual is written with the assumption that you are using an Informix
database server, Version 7.x or later.
Informix offers two implementations of the 4GL application development
language:
B The INFORMIX-4GL C Compiler uses a preprocessor to generate
Informix ESQL/C source code. This code is preprocessed in turn to
produce C source code, which is then compiled and linked as object
code in an executable command le.
B The INFORMIX-4GL Rapid Development System (RDS) uses a
compiler to produce pseudo-machine code (called p-code) in a single
step. You then invoke a runner to execute the p-code version of your
application.
Both versions of 4GL use the same 4GL statements. Chapter 1, Compiling
INFORMIX-4GL Source Files, describes the differences between the two
versions of 4GL and explains how to use both versions.
You can easily use applications developed with an earlier version of 4GL,
such as Version 4.x or 6.x or 7.2, with this version of 4GL. For RDS programs
that use p-code, however, you must rst recompile your 4GL source code.
6 INFORMIX- 4GL Reference Manual
Assumpti ons About Your Local e
Assumptions About Your Locale
Informix products can support many languages, cultures, and code sets.
All culture-specic information is brought together in a single environment,
called a GLS (Global Language Support) locale.
Examples in this manual are written with the assumption that you are using
the default locale, en_us.8859-1. This supports U.S. English format conven-
tions for dates, times, and currency, and the ISO 8859-1 code set. Some
versions of this locale support various non-ASCII 8-bit characters such as , ,
and . Like all locales that Informix provides with its GLS libraries, however,
the default locale supports the ASCII characters (as listed in Appendix A).
If you plan to use non-ASCII characters in your data or your SQL identiers,
or if you want nondefault collation of character data, you need to specify the
appropriate nondefault locale. For instructions on how to specify a nonde-
fault locale, additional syntax, and other considerations related to GLS, see
the Informix Guide to GLS Functionality. See also Appendix E, Developing
Applications with Global Language Support.
Demonstration Database and Examples
4GL includes several 4GL demonstration applications, along with a demon-
stration database called stores7 that contains information about a ctitious
wholesale sporting-goods distributor. You can create the stores7 database in
the current directory by entering the following command:
dbaccessdemo7
Many (but not all) of the examples in the 4GL documentation set are based on
the stores7 database. This database is described in detail in Appendix A of
INFORMIX-4GL by Example. For more information on creating the demon-
stration database and using the examples, see the introduction to INFORMIX-
4GL by Example.
Introducti on 7
Accessi ng Databases from Wi thi n 4GL
Accessing Databases from Within 4GL
The 4GL language approximates a superset of the Informix implementation
of the industry-standard SQL language. Because the 4GL compiler does not
recognize some SQL statements, however, three methods are supported for
including SQL statements within the 4GL program:
B For most SQL syntax that was supported by Informix 4.1 database
servers, you can directly embed SQL statements in 4GL source code.
B For SQL statements that can be prepared, you can use the PREPARE
feature of SQL to include SQL statements as text in prepared objects.
B For all SQL statements that can be prepared, you can also use the
SQL ... END SQL delimiters to enclose the SQL statement. Unlike
PREPARE, these can include host variables for input and output.
You must use one of the last two methods for SQL statements that include
syntax that was introduced later than Informix 4.1 database servers. Such
embedded, prepared, or delimited SQL statements are passed on to the
database server for execution, as in the following 4GL program fragment:
DEFINE bugfile, setdeb CHAR(255)
DATABASE stores7 --Directly embedded SQL
LET setdeb = "set debug file to /u/tanya/bugfile"
PREPARE bugfile FROM setdeb --Prepared SQL (post-4.1)
EXECUTE IMMEDIATE bugfile --Directly embedded SQL
SQL SET PDQPRIORITY HIGH --Delimited SQL (post-4.1)
END SQL
Appendix I, SQL Statements That Can Be Embedded in 4GL Code, lists the
supported SQL syntax.
If you are uncertain which method is needed, use SQLENDSQL delimiters,
which generally offer wider functionality and greater ease of coding than
PREPARE for SQL statements that cannot be directly embedded.
For additional information on SQL statements, see Informix Guide to SQL:
Syntax.
8 INFORMIX- 4GL Reference Manual
Documentati on Conventi ons
Documentation Conventions
This section describes certain conventions that this manual uses.
These conventions make it easier to gather information from this and other
volumes in the documentation set. The following conventions are discussed:
B Typographical conventions
B Icon conventions
B Example-code conventions
B Syntax conventions
Typographical Conventions
This manual uses the following conventions to introduce new terms,
illustrate screen displays, describe command syntax, and so forth.
Tip: When you are instructed to enter characters or to execute a command,
immediately press RETURN after the entry. When you are instructed to type the
text or to press other keys, no RETURN is required.
Convention Meaning
KEYWORD All primary elements in a programming language statement
(keywords) appear in uppercase letters in a serif font.
italics
italics
italics
Within text, new terms and emphasized words appear in italics.
Within syntax diagrams and code examples, identiers or values
that you are to specify appear in italics.
boldface
boldface
Names of program entities (such as classes, events, and tables),
environment variables, le and pathnames, and interface
elements (such as icons, menu items, and buttons) appear in
boldface.
monospace
monospace
Information that the product displays and information that you
enter appear in a monospace typeface.
KEYSTROKE Keys to press appear in uppercase letters in a sans serif font.
Introducti on 9
Icon Conventi ons
Icon Conventions
Throughout the documentation, youwill ndtext that is identiedby several
different types of icons. This section describes these icons.
Feature, Product, and Platform Icons
Feature, product, and platform icons identify paragraphs that contain
feature-specic, product-specic, or platform-specic information.
These icons can apply to a rowin a table, one or more paragraphs, or an entire
section. A symbol indicates the end of the feature-specic, product-
specic, or platform-specic information.
Compliance Icons
Compliance icons indicate paragraphs that provide guidelines for complying
with a standard.
These icons can apply to a rowin a table, one or more paragraphs, or an entire
section. A symbol indicates the end of the compliance information.
Icon Description
Identies information that relates to the Informix Global
Language Support (GLS) feature.
Identies information or syntax that is specic to Informix
Dynamic Server.
Identies information or syntax that is specic to
INFORMIX-SE.
Identies SQL statements that you must put in an SQL
block or prepare statement.
Icon Description
Identies information that is specic to an ANSI-compliant
database
GLS
IDS
SE
SQL
ANSI
10 INFORMIX- 4GL Reference Manual
Exampl e- Code Conventi ons
Example-Code Conventions
Examples of 4GL source code occur in several sections of this manual.
For readability, 4GL or SQL keywords generally appear in uppercase
characters in code examples, and identiers usually appear in lowercase or
mixed case.
For instance, you might see code as in the following example:
MENU "CUSTOMER"
COMMAND "Query" "Search for a customer"
CALL query_data( )
NEXT OPTION "Modify"
...
COMMAND "Modify" "Modify a customer"
...
END MENU
Ellipsis ( ) symbols in a code example indicate that more code would be
added in a complete application, but for clarity and simplicity, the example
omits code that is extraneous to the current topic. (In most contexts, a
compile-time or runtime error occurs if literal ellipsis symbols appear in
code, or if you omit code that is necessary to your program logic.) Ellipsis
symbols do not begin or endcode examples, however, even if additional code
would be required for a complete program, or for a complete statement.
Most 4GL code examples are fragments of programs, rather than complete
programs that can be compiled and executed. Because most examples are
provided to illustrate some specic topic, the examples sometimes do not
strictly conformto good programming practice. For example, they might not
check to verify that an operation successfully executed without error, or they
might not include the comments that normally should be included to
improve readability and simplify maintenance of your code.
Syntax Conventions
SQL statement syntax is described in the Informix Guide to SQL: Syntax.
The syntax for 4GL statements is described in Chapter 4 of this manual.
Most chapters of this book describe the syntax of some aspect of the 4GL
language, such as expressions, form specications, and reports.
Introducti on 11
Syntax Conventi ons
This section describes conventions for syntax diagrams. Each diagram
displays the sequences of required and optional keywords, terms, and
symbols that are valid in a given statement or segment. Figure 1 shows the
syntax diagram of the OPEN FORM statement.
Each syntax diagram begins at the upper-left corner and ends at the upper-
right corner with a vertical terminator. Between these points, any path that
does not stop or reverse direction describes a possible formof the statement.
(For a fewdiagrams, however, notes in the text identify path segments that
are mutually exclusive.)
Syntax elements in a path represent terms, keywords, symbols, andsegments
that can appear in your statement. The path always approaches elements
from the left and continues to the right, except in the case of separators in
loops. For separators in loops, the path approaches counterclockwise. Unless
otherwise noted, at least one blank character separates syntax elements.
Elements That Can Appear on the Path
You might encounter one or more of the following elements on a path.
Figure 1
Example of a Simple Syntax Diagram
Element Description
KEYWORD Awordin UPPERCASEletters is a keyword. Youmust
spell the word exactly as shown; you can, however,
use either uppercase or lowercase letters.
( . , ; @ + * - / ) Punctuation and other nonalphanumeric characters
are literal symbols that you must enter exactly as
shown.
" "
' '
Double quotation marks must be entered as shown. If
you prefer, a pair of double quotation marks can
replace a pair of single quotation marks, but you
cannot mix double and single quotation marks.
(1 of 3)
OPEN FORM form FROM "lename"
12 INFORMIX- 4GL Reference Manual
Syntax Conventi ons
variable A word in italics represents a value that you must
supply. A table that follows the diagram explains the
value.
Areference in a box represents a subdiagram. Imagine
that the subdiagram is spliced into the main diagram
at this point. When a page number is not specied, the
subdiagram appears on the same page. The aspect
ratios of boxes are not signicant.
Areference to SQL:S in a syntax diagramrepresents an
SQL statement or segment that is described in the
Informix Guide to SQL: Syntax. Imagine that the
segment were spliced into the diagram at this point.
An icon is a warning that this path is valid only for
some products, or conditions. The following icons
appear in some syntax diagrams:
This path is valid only for
INFORMIX-SE database servers.
This path is valid only for Informix
Dynamic Server.
This path is an Informix extension to
the ANSI SQL-92 entry-level SQL
standard.
Ashaded option is the default, if you provide no other
specication.
A syntax segment within a pair of arrows is a
subdiagram.
The vertical line terminates the syntax diagram.
A branch below the main path indicates an optional
path. (Any term on the main path is required, unless
a branch can circumvent it.)
Element Description
(2 of 3)
ATTRIBUTE
Clause
p. 3-288
ATTRIBUTE Clause
SELECT Statement
see SQL:S
SE
SE
IDS
+
ALL
. . .
NOT
IS NULL
Introducti on 13
Syntax Conventi ons
How to Read a Syntax Diagram
Figure 2 shows a syntax diagramthat uses some of the path elements that the
previous table lists.
The Case III label above the diagram implies that this statement can have at
least two other syntax patterns. To use this diagramto construct a statement,
start at the top left with the keyword DISPLAY. Then follow the diagram to
the right, proceeding through the options that you want.
A set of multiple branches indicates that a choice
among more than two different paths is available.
A loop indicates a path that you can repeat.
Punctuation along the top of the loop indicates the
separator symbol for list items.
If no symbol appears, a blank space is the separator, or
(as here) the Linefeed that separates successive state-
ments in a source module.
Agate ( ) on a path indicates that you can only use
that path the indicated number of times, even if it is
part of a larger loop. You can specify size no more than
three times within this statement segment.
Element Description
(3 of 3)
ERROR
NOT FOUND
WARNING
,
variable
statement
3
,
size
3
Figure 2
Example of a Syntax Diagram
ATTRIBUTE Clause
variable
,
value
,
DISPLAY
BY NAME
Field Clause
,
TO
Case III: (di spl ay output i n a screen form)
14 INFORMIX- 4GL Reference Manual
Syntax Conventi ons
Figure 2 illustrates the following steps:
1. Type the keyword DISPLAY.
2. You can display the values of a list of variables to an explicit list of
elds within the current screen form:
B Type the name of a value. If you want to display several values,
separate successive values by a comma.
B Type the keyword TO after the name of the last value.
B Type the name of a eld in the current form in which to display
the rst value. To nd the syntax for specifying eld names, go to
the Field Clause segment on the specied page.
3. If you are using a form whose elds have the same names as the
values that you want to display, you can follow the lower path:
B Type the keywords BY NAME after DISPLAY.
B Type the name of a variable. If you want to display the values of
several variables, separate successive variables by comma.
4. You can optionally set a screen attribute for the displayed values:
B Use the syntax of the ATTRIBUTE Clause segment on the
specied page to specify the screen attribute that you desire.
5. Follow the diagram to the terminator.
Your DISPLAY TO or DISPLAY BY NAME statement is now complete.
Arestriction on step 2 (that there must be as many elds as variables)
appears in notes that followthe diagram, rather than in the diagram
itself. If 4GL issues an error when you compile a statement that seems
to followthe syntax diagram, it might be a good idea to also read the
usage notes for that statement.
Introducti on 15
Addi ti onal Documentati on
Additional Documentation
For additional information, you might want to refer to the following types of
documentation:
B Documentation included with 4GL
B On-line manuals
B On-line help
B On-line error messages
B Related reading
Documentation Included with 4GL
The INFORMIX-4GL documentation set includes the following additional
manuals:
B INFORMIX-4GL Installation Guide is a pamphlet that describes howto
install the various 4GL products.
B INFORMIX-4GL Concepts and Use introduces 4GL and provides the
context needed to understand the other manuals in the documen-
tation set. It covers 4GL goals (what kinds of programming the
language is meant to facilitate), concepts and nomenclature (parts of
a program, ideas of database access, screen form, and report gener-
ation), and methods (how groups of language features are used
together to achieve particular effects).
B INFORMIX-4GL by Example is a collection of 30 annotated 4GL
programs. Each is introduced with an overview; then the program
source code is shown with line-by-line notes. The program source
les are distributed as text les with the product; scripts that create
the demonstration database and copy the applications are also
included.
B Documentation Notes, which contain additions and corrections to the
manuals, and Release Notes are located in the directory where the
product is installed. Please examine these les because they contain
vital information about application and performance issues.
16 INFORMIX- 4GL Reference Manual
On- Li ne Manual s
If you have also purchased the INFORMIX-4GL Interactive Debugger product
(which requires the INFORMIX-4GL Rapid Development System), your 4GL
documentation also includes the following manual:
B Guide to the INFORMIX-4GL Interactive Debugger is both an intro-
ductionto the Debugger anda comprehensive reference of Debugger
commands and features. The Debugger allows you view the source
code and to interact with your 4GL programs while they are running.
It helps you to analyze the logic of your 4GL program and to
determine the source of runtime errors within your programs.
On-Line Manuals
The Informix Answers OnLine CD allows you to print chapters or entire
books and perform full-text searches for information in specic books or
throughout the documentation set. You can install the documentation or
access it directly fromthe CD. For information about howto install, read, and
print on-line manuals, see the installation insert that accompanies Answers
OnLine. You can also access Answers OnLine on the Web at the following
URL:
http://www.informix.com/answers
On-Line Help
The Programmers Environment of 4GL provides on-line help; you can
invoke help by pressing CONTROL-W.
On-Line Error Messages
Use the nderr script to display a particular error message or messages on
your screen. The script is located in the $INFORMIXDIR/bin directory.
Introducti on 17
On- Li ne Error Messages
The nderr script has the following syntax.
For example, to display the -359 error message, you can enter either of the
following:
finderr -359
or, equivalently:
finderr 359
The following example demonstrates howto specify a list of error messages.
The example also pipes the output to the UNIX more command to control the
display. You can also direct the output to another le so that you can save or
print the error messages:
finderr 233 107 113 134 143 144 154 | more
A few messages have positive numbers. These messages are used solely
within the application tools. In the unlikely event that you want to display
them, you must precede the message number with the + sign.
The messages numbered-1 to -100 canbe platform-dependent. If the message
text for a message in this range does not apply to your platform, check the
operating system documentation for the precise meaning of the message
number.
msg_num Indicates the number of the error message to display. Error message
numbers range from -1 to -32000. Specifying the - sign is optional.
nderr msg_num
18 INFORMIX- 4GL Reference Manual
Rel ated Readi ng
Related Reading
The following Informix database server publications provide additional
information about the topics that this manual discusses:
B Informix database servers and the SQL language are described in
separate manuals, including Informix Guide to SQL: Tutorial, Informix
Guide to SQL: Syntax, and Informix Guide to SQL: Reference.
B Information about setting up Informix database servers is provided
in the Administrators Guide for your Informix database server.
Informix Press, in partnership with Prentice Hall, publishes books about
Informix products. Authors include experts from Informix user groups,
employees, consultants, and customers. Recent titles about INFORMIX-4GL
include:
B Advanced INFORMIX-4GL Programming, by Art Taylor, 1995.
B Programming Informix SQL/4GL: A Step-by-Step Approach, by Cathy
Kipp, 1998.
B Informix Basics, by Glenn Miller, 1998.
You can access Informix Press on the Web at the following URL:
http://www.informix.com/ipress
Informix Developer Network
Informix maintains the Informix Developer Network (IDN) as a resource by
which developers of Informix-based applications can exchange information
with their peers and with Informix experts. You can access the Informix
Developer Network on the Web at the following URL:
http://www.informix.com/idn
Introducti on 19
Informi x Wel comes Your Comments
Informix Welcomes Your Comments
Let us know what you like or dislike about our manuals. To help us with
future versions of our manuals, we want to know about any corrections or
clarications that you would nd useful. Include the following information:
B The name and version of the manual that you are using
B Any comments that you have about the manual
B Your name, address, and phone number
Write to us at the following address:
Informix Software, Inc.
Technical Publications Department
4100 Bohannon Drive
Menlo Park, CA 94025
If you prefer to send electronic mail, our address is:
[email protected]
We appreciate your suggestions.
Important: The docalias is monitored only by the Informix departments that create
and maintain manuals and on-line documentation les. It is not an appropriate
channel for technical support issues, sales inquiries, or questions about the avail-
ability of Informix products.
1
Chapter
Compiling INFORMIX-4GL
Source Files
In This Chapter . . . . . . . . . . . . . . . . . . . . 1-3
Two Implementations of INFORMIX-4GL . . . . . . . . . . . 1-3
Differences Between the C Compiler and RDS Versions . . . . . 1-4
Differences in the Programmers Environment . . . . . . 1-4
Differences in Commands . . . . . . . . . . . . . 1-5
Differences in Filename Extensions . . . . . . . . . . 1-5
The C Compiler Version . . . . . . . . . . . . . . . . . 1-6
The Five-Phase 4GL Compilation Process. . . . . . . . . . 1-6
The Programmers Environment . . . . . . . . . . . . . 1-8
The INFORMIX-4GL Menu . . . . . . . . . . . . . 1-8
The MODULE Design Menu . . . . . . . . . . . . 1-9
The FORM Design Menu . . . . . . . . . . . . . . 1-14
The PROGRAM Design Menu . . . . . . . . . . . . 1-19
The QUERY LANGUAGE Menu . . . . . . . . . . . 1-26
Creating Programs in the Programmers Environment . . . . . 1-26
Creating a New Source Module . . . . . . . . . . . . 1-27
Revising an Existing Module. . . . . . . . . . . . . 1-27
Compiling a Source Module . . . . . . . . . . . . . 1-28
Linking Program Modules . . . . . . . . . . . . . 1-29
Executing a Compiled Program. . . . . . . . . . . . 1-31
Creating Programs at the Command Line. . . . . . . . . . 1-32
Creating or Modifying a 4GL Source File . . . . . . . . 1-33
Compiling a 4GL Module . . . . . . . . . . . . . . 1-33
Compiling and Linking Multiple Source Files . . . . . . . 1-33
Using the c4gl Script for Compilation. . . . . . . . . . 1-34
The -globcurs and -localcurs Options . . . . . . . . . . 1-38
Shared Libraries . . . . . . . . . . . . . . . . . 1-40
Invoking a Compiled 4GL Program at the Command Line . . 1-44
Program Filename Extensions . . . . . . . . . . . . . 1-45
1-2 INFORMIX- 4GL Reference Manual
The Rapid Development System . . . . . . . . . . . . . . 1-47
The Programmers Environment . . . . . . . . . . . . . 1-47
The INFORMIX-4GL Menu . . . . . . . . . . . . . 1-47
The MODULE Design Menu . . . . . . . . . . . . . 1-48
The FORM Design Menu . . . . . . . . . . . . . . 1-54
The PROGRAM Design Menu . . . . . . . . . . . . 1-59
The QUERY LANGUAGE Menu . . . . . . . . . . . 1-66
Creating Programs in the Programmers Environment . . . . . 1-67
Creating a New Source Module . . . . . . . . . . . . 1-67
Revising an Existing Module . . . . . . . . . . . . . 1-68
Compiling a Source Module . . . . . . . . . . . . . 1-68
Combining Program Modules . . . . . . . . . . . . 1-69
Executing a Compiled RDS Program . . . . . . . . . . 1-71
Invoking the Debugger . . . . . . . . . . . . . . . 1-72
Creating Programs at the Command Line . . . . . . . . . . 1-72
Creating or Modifying a 4GL Source File. . . . . . . . . 1-74
Compiling an RDS Source File . . . . . . . . . . . . 1-74
Concatenating Multi-Module Programs . . . . . . . . . 1-76
Running RDS Programs . . . . . . . . . . . . . . 1-77
Running Multi-Module Programs . . . . . . . . . . . 1-78
Running Programs with the Interactive Debugger . . . . . 1-79
RDS Programs That Call C Functions . . . . . . . . . . 1-79
Editing the fgiusr.c File . . . . . . . . . . . . . . . 1-80
Creating a Customized Runner . . . . . . . . . . . . 1-82
Running Programs That Call C Functions . . . . . . . . 1-85
Program Filename Extensions . . . . . . . . . . . . . . 1-86
Compi l i ng INFORMIX- 4GL Source Fi l es 1-3
In This Chapter
This chapter describes how to create INFORMIX-4GL source-code modules,
and how to produce executable 4GL programs from these modules, both at
the operating system prompt and in the Programmers Environment.
Procedures to do this are shown for the INFORMIX-4GL C Compiler, as well as
for the INFORMIX-4GL Rapid Development System. These two implementa-
tions of 4GL differ in how they process 4GL source-code modules. This
chapter begins by identifying differences between the two implementations
of 4GL. It then goes on to describe each implementation of 4GL.
Except as otherwise noted, the other chapters and appendixes of this manual
describe features that are identical in both the C Compiler and the Rapid
Development System implementations of 4GL.
Two Implementations of INFORMIX-4GL
To write a 4GL program, you must rst create an ASCII le of 4GL statements
that performlogical tasks to support your application. This chapter explains
the procedures by which you can transformone or more source-code les of
4GL statements into an executable 4GL program. Informix offers two imple-
mentations of the 4GL application development language:
B The INFORMIX-4GL C Compiler, whose preprocessor generates
extended ESQL/C source code. This code is further processed in
several steps to produce Csource code, whichis compiledandlinked
as object code in an executable command le.
B The INFORMIX-4GL Rapid Development System (RDS), which uses a
compiler to produce pseudo-machine code (called p-code) in a single
step. You then invoke a runner to execute the p-code version of your
application. For more details, see Compiling and Linking Multiple
Source Files on page 1-33.
1-4 INFORMIX- 4GL Reference Manual
Di fferences Between the C Compi l er and RDS Versi ons
Important: This version of the runner or Debugger cannot interpret programs
compiled to p-code by releases of 4GL earlier than Version 7.30. You must rst
recompile your source les and form specications. Similarly, releases of the 4GL
runner or Debugger earlier than Version 7.30 cannot interpret p-code that this
release produces.
Differences Between the C Compiler and RDS Versions
Both implementations of 4GL use the same 4GL statements and nearly
identical Programmers Environments. Because they use different methods
to compile 4GL source les into executable programs, however, there are a
few differences in the user interfaces.
Differences in the Programmers Environment
The Programmers Environment is a system of menus that supports the
various steps in the process of developing 4GL application programs. The
Drop option on the PROGRAM design menu of the C Compiler is called
Undene in the Rapid Development Systemimplementation.
The New and Modify options of the PROGRAM design menu display a
different screen formin the two implementations. Both of these screen forms
are illustrated later in this chapter.
The 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. (The Debugger is based on p-code, so it can execute only 4GL
programs and modules that have been compiled by the Rapid Development
System.)
The INFORMIX-4GL Interactive Debugger is available as a separate product.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-5
Di fferences Between the C Compi l er and RDS Versi ons
Differences in Commands
The commands you use to enter the Programmers Environments, compile
and execute 4GL programs, and build or restore the stores7 demonstration
database vary between implementations of 4GL.
The C Compiler requires no equivalent command to the fglgo command,
because its compiled object les are executable without a runner. The Rapid
Development System also contains a command-le script to compile and
execute 4GL programs that call C functions or INFORMIX-ESQL/C functions,
as described in RDS Programs That Call C Functions on page 1-79.
Differences in Filename Extensions
The differences in lename extensions are as follows.
The backup le extensions .4bo and .4be for compiled modules and
programs have the same names in both implementations. These les are not
interchangeable between the two 4GL implementations, however, because
object code produced by a C compiler is different from p-code.
Other lename extensions that are the same in both the C Compiler and the
Rapid Development System designate interchangeable les, if you use both
implementations of 4GL to process the same 4GL source-code module.
C Compiler RDS Effect of Command
i4gl r4gl Enter Programmers Environment
c4gl sle.4gl fglpc sle Compile 4GL source le sle.4gl
xle.4ge fglgo xle Execute compiled 4GL programxle
i4gldemo r4gldemo Create the demonstration database
C Compiler RDS Signicance of Extension
.o .4go Compiled 4GL source-code module
.4ge .4gi Executable (runable) 4GL program le
1-6 INFORMIX- 4GL Reference Manual
The C Compi l er Versi on
The C Compiler Version
This section describes the following aspects of the C compiler version of 4GL:
B The ve steps of the compilation process
B All the menu options and screen form elds of the Programmers
Environment
B The steps for compiling and executing 4GL programs from the
Programmers Environment
B The equivalent command-line syntax for compiling and executing
4GL programs
B The lename extensions of 4GL source-code, object, error, and
backup les
The Five-Phase 4GL Compilation Process
Versions of 4GL earlier than 6.0 were built on ESQL/C. To make 4GL more
independent of ESQL/C, the compilation sequence requires one or more extra
processes. Figure 1-1 on page 1-7 shows the ve compilation phases in
INFORMIX-4GL 6.0 and subsequent release versions. The ve phases are as
follows:
1. The i4glc1 preprocessor converts a 4GL source le with.4gl extension
into a le with .4ec extension. It parses the 4GL language and
generates C code to handle function and report denitions, compu-
tations, and function calls. It generates extended ESQL/C statements
to handle forms, menus, input statements, and display statements,
and pure ESQL/C to handle SQL statements and declarations of
variables. i4glc1 is similar to Version 4.12 and earlier fglc, except that
i4glc1 generates a .4ec le instead of a .ec le.
2. The i4glc2 preprocessor translates the extended form, menu, input,
and display statements to pure C code but leaves variable declara-
tions and SQL statements unchanged. i4glc2 accepts a .4ec le
generated by i4glc1 as input and produces a .ec le containing pure
ESQL/C code.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-7
The Fi ve- Phase 4GL Compi l ati on Process
3. The i4glc3 preprocessor is a copy of the ESQL/C compiler. The i4glc3
preprocessor accepts a .ec le (produced by i4glc2 or written as pure
ESQL/C code), and produces a .c le. The declarations and the SQL
statements are mapped to pure C language code.
4. The i4glc4 preprocessor converts C code, which may contain non-
ASCII characters in variable names, into de-internationalized names.
This step ensures that dening a record like table.* or a eld like
table.column does not produce C code that contains non-ASCII
character in identiers (because very few C compilers accept non-
ASCII characters in the names of variables).
5. Informix uses the systemCcompiler to convert the Ccode generated
by i4glc3 or i4glc4 into object les (a le with .o extension) and
executable programs (a le with .4ge extension).
Figure 1-1
Five-Phase
Compilation
Process

i 4gl c1
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
l e.4gl
l e.4ec
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
l e.ec
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
l e.c
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
\ \ \ \ \ \ \ \ \
l e.c

l e.o or
l e.4ge
i 4gl c2
i 4gl c3
i 4gl c4
CC
1-8 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Programmers Environment
The C Compiler provides a series of nested menus, called the Programmers
Environment. These menus support the steps of 4GL program development
and keep track of the components of your application. You can invoke the
Programmers Environment by entering i4gl at the system prompt.
The INFORMIX-4GL Menu
The i4gl command briey displays the INFORMIX-4GL banner. Then a menu
appears, called the INFORMIX-4GL menu.
This is the highest menu, from which you can reach any other menu of the
Programmers Environment. You have ve options:
B Module. Work on a 4GL program module.
B Form. Work on a screen form.
B Program. Specify components of a multi-module program.
B Query-language. Use an SQL interactive interface, if you have either
INFORMIX-SQL or DB-Access installed on your system. (See the
documentation of these Informix products for details of their use.)
B Exit. Terminate i4gl and return to the operating system.
The rst three options display newmenus that are describedin the pages that
follow. (You can also press CONTROL-Wat any menu to display an on-line help
message that describes your options.) As at any 4GL menu, you can choose
an option in either of two ways:
B By typing the rst letter of the option
B By using the SPACEBAR or arrow keys to move the highlight to the
option that you choose, and then pressing RETURN
INFORMIX-4GL: Module Form Program Query-language Exit
Create, modify, or run individual 4GL program modules.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-9
The Programmer s Envi ronment
The MODULE Design Menu
You can press RETURN or type m or M to choose the Module option of the
INFORMIX-4GL menu. This displays a newmenu, calledthe MODULE design
menu. Use this menu to work on an individual 4GL source-code module.
Use this menu to create and compile source-code modules of a 4GL appli-
cation. (For information on creating and compiling 4GL screen forms, see
The FORM Design Menu on page 1-14. For details of how to create and
compile help messages, see the mkmessage utility in Appendix B,
INFORMIX-4GL Utility Programs.)
The MODULE design menu supports the following options:
B Modify. Change an existing 4GL source-code module.
B New. Create a new source-code module.
B Compile. Compile a source-code module.
B Program_Compile. Compile a 4GL application program.
B Run. Execute a compiled 4GL program module or a multi-module
application program.
B Exit. Return to the INFORMIX-4GL menu.
Within the Programmers Environment, the Exit option returns control to the
higher menu from which you accessed the current menu (or, when you
choose Exit from the INFORMIX-4GL menu, terminates the 4GL session and
returns to the system prompt).
MODULE: Modify New Compile Program_Compile Run Exit
Change an existing 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
1-10 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Modify Option
Choose this option to edit an existing 4GL source-code module. If you choose
this option, 4GL requests the name of the 4GL source-code le to be modied
and then prompts you to specify a text editor. If you have designated a
default editor with the DBEDIT environment variable (which is described in
Appendix D) or if you specied an editor at the Programmers Environment
previously in this session, 4GL invokes that editor. The .4gl source le whose
lename you specied is the current le.
When you leave the editor, 4GL displays the MODIFY MODULE menu, with
the Compile option highlighted.
If you press RETURN or type c or C to choose the Compile option, 4GL displays
the COMPILE MODULE menu:
The Object option creates a compiled le with the .o extension but makes no
attempt to link the le with other les.
MODIFY MODULE: Compile Save-and-exit Discard-and-exit
Compile the 4GL module specification.
-------------------------------------------------Press CTRL-W for Help------
COMPILE MODULE: Object Runable Exit
Create object file only; no linking to occur.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-11
The Programmer s Envi ronment
The Runable option creates a compiled le with the .4ge extension. 4GL
assumes that the current module is a complete 4GL program, and that no
other module needs to be linked to it. Choose the Runable option if the
current programmodule is a stand-alone 4GL program. If this is not the case
(that is, if the le is one of several 4GL source-code modules within a multi-
module program), then you should use the Object option instead, and you
must use the PROGRAMdesign menu to specify all the component modules.
After you choose Object or Runable, a message near the bottomof the screen
will advise you if 4GL issues a compile-time warning or error. If there are
warnings (but no errors), an object le is produced. Choose the Exit option of
the next menu, andthenSave-and-exit at the MODIFYMODULE menu, if you
wish to save the executable le without reading the warnings.
Alternatively, you can examine the warning messages by choosing Correct
at the next menu. When you nish editing the .err le that contains the
warnings, you must choose Compile again from the MODIFY MODULE
menu, because the Correct option deletes the executable le.
If there are compilation errors, the following menu appears.
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 because 4GL does this for you. Correct your source le, save
your changes, and exit from the editor. The MODIFY MODULE menu
reappears, prompting you to recompile, save, or discard your changes
without compiling.
If you choose not to correct the errors, you are prompted to Save or Discard
the le.
COMPILE MODULE: Correct Exit
Correct errors in the 4GL module.
-------------------------------------------------Press CTRL-W for Help------
1-12 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
If there are no compilation errors, the MODIFY MODULE menu appears with
the Save-and-Exit option highlighted. Choose this option to save the current
source-code module as a le with extension .4gl, and create an object le with
the same lename, but with the extension .o. If you specied Runable when
you compiled, the executable version is saved with the extension .4ge. The
Discard-and-Exit option discards any changes that were made to your le
after you chose the Modify option.
The New Option
Choose this option to create a new4GL source-code module.
This option resembles the Modify option, but NEW MODULE is the menu
title, and you must enter a new module name, rather than choose it from a
list.
The lename of the module must be unique among source-code modules of
the same 4GL program, and can include up to 10 characters, not including the
.4gl le extension. 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.
MODULE: Modify New Compile Program_Compile Run Exit
Create a new 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-13
The Programmer s Envi ronment
The Compile Option
The Compile option enables you to compile an individual 4GL source-code
module.
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.
The Program_Compile Option
The Program_Compile option of the MODULE design menu is the same as
the Compile option of the PROGRAMdesign menu. This option can compile
and link modules, as described in the programspecication database, taking
into account the time when the modules were last updated.
This option is useful after you modify a single module of a complex program,
and need to test it by compiling and linking it with the other modules.
The Run Option
Choose the Run option to begin execution of a compiled 4GL program.
MODULE: Modify New Compile Program_Compile Run Exit
Compile an existing 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
MODULE: Modify New Compile Program_Compile Run Exit
Execute an existing 4GL program module or application program.
-------------------------------------------------Press CTRL-W for Help------
1-14 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The RUN PROGRAM screen lists compiled modules and programs, with the
highlight on the module corresponding to the current le, if any has been
specied. Only compiled programs with extension .4ge are listed. If you
compile a programoutside the Programmers Environment and you want it
to appear in this list, give it the extension .4ge.
If no compiled programs exist, 4GL displays an error message and returns to
the MODULE design menu. You can exit to the maine INFORMIX-4GL menu,
and select the Program option to create the database.
The Exit Option
Choose this option to exit from the MODULE design menu and display the
INFORMIX-4GL menu.
The FORM Design Menu
You can type f or F at the INFORMIX-4GL menu to choose the Form option.
This option displays a menu, called the FORM design menu.
MODULE: Modify New Compile Program_Compile Run Exit
Returns to the INFORMIX-4GL menu.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Change an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-15
The Programmer s Envi ronment
You can use this menu to create, modify, and compile screen form specica-
tions. These dene visual displays that 4GL applications can use to query and
modify the information in a database. 4GL form specication les are ASCII
les that are described in Chapter 6, Screen Forms.
The FORM design menu supports the following options:
B Modify. Change an existing 4GL screen form specication.
B Generate. Create a default 4GL screen form specication.
B New. Create a new4GL screen form specication.
B Compile. Compile an existing 4GL screen form specication.
B Exit. Return to the INFORMIX-4GL 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 FORMdesign menu enables you to edit an existing
formspecication le. It resembles the Modify option in the MODULE design
menu, because both options are used to edit program modules.
If you choose this option, you are prompted to choose the name of a form
specication le to modify. Source les created at the FORM design menu
have the le extension .per. (If you use a text editor outside of the
Programmers Environment to create formspecication les, you must give
them the extension .per before you can compile them with the FORM4GL
screen form facility.)
FORM: Modify Generate New Compile Exit
Change an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
1-16 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
If you have not already designated a text editor in this 4GL session or with
DBEDIT, you are prompted for the name of an editor. Then an editing session
begins, with the form specication source-code le that you specied as the
current le. When you leave the editor, 4GL displays the MODIFY FORM
menu with the Compile option highlighted. Now you can press RETURN to
compile the revised form specication le.
If there are compilation errors, 4GL displays the COMPILE FORM menu.
Press RETURN to choose 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. 4GL automatically deletes these
messages when you save the le and exit from the editor. After you have
corrected the errors, the MODIFY FORM menu appears again, with the
Compile option highlighted. Press RETURN to recompile. Repeat these steps
until the compiler reports no errors. (If you choose Exit instead of Correct,
you are prompted to Save or Discard the le.)
If there are no compilation errors, you are prompted to save the modied
form specication le and the compiled form, or to discard the changes.
(Discarding the changes restores the version of your formspecications from
before you chose the Modify option.)
MODIFY FORM: Compile Save-and-exit Discard-and-exit
Compile the form specification.
-------------------------------------------------Press CTRL-W for Help------
COMPILE FORM: Correct Exit
Correct errors in the form specification.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-17
The Programmer s Envi ronment
The Generate Option
You can type g or G to choose the Generate option. This option creates a
simple default screen formthat you can use directly in your program, or that
you can later edit by choosing the Modify option.
When youchoose this option, 4GL prompts youto select a database, to choose
a lename for the formspecication, and to identify the tables that the form
will access. After you provide this information, 4GL creates and compiles a
form specication le. (This is equivalent to running the -d (default) option
of the form4gl command, as described in Compiling a Form at the
Command Line on page 6-88.)
The New Option
The Newoption of the FORMdesign menuenables youto create a newscreen
form specication.
After prompting you for the name of your formspecication le, 4GL places
you in the editor where you can create a form specication le. When you
leave the editor, 4GL transfers you to the NEW FORM menu that is like the
MODIFY FORMmenu. You can compile your formand correct it in the same
way.
FORM: Modify Generate New Compile Exit
Generate and compile a default form specification.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Create a new form specification.
-------------------------------------------------Press CTRL-W for Help------
1-18 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Compile Option
The Compile option enables you to compile an existing form specication
le without going through the Modify option.
4GL compiles the form specication le whose name you specify. If the
compilation fails, 4GL displays the COMPILE FORM menu with the Correct
option highlighted.
The Exit Option
The Exit option restores the INFORMIX-4GL menu.
FORM: Modify Generate New Compile Exit
Compile an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Returns to the INFORMIX-4GL menu.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-19
The Programmer s Envi ronment
The PROGRAM Design Menu
A 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 create separate 4GL modules. The
INFORMIX-4GL menu includes the Program option to create multi-module
programs. If you choose this option, 4GL searches your DBPATH directories
for the program design database, which stores the names of the objects that are
usedto create programs andtheir builddependencies. (For more information
on the DBPATHenvironment variable, see Appendix D.)
This program design database describes the component modules and
function libraries of your 4GL program. By default, its name is syspgm4gl,
but you can use the PROGRAM_DESIGN_DBS environment variable to
specify some other name. (For more information on the
PROGRAM_DESIGN_DBS environment variable, see Appendix D.)
If 4GL cannot nd this database, you are asked if you want one created. If you
enter y in response, 4GL creates the syspgm4gl database, grants CONNECT
privileges to PUBLIC, and displays the PROGRAMdesign menu. As database
administrator of syspgm4gl, you can later restrict the access of other users.
If syspgm4gl already exists, the PROGRAM design menu appears.
You can use this menu to create or modify a multi-module 4GL program
specication, to compile and link a program, or to execute a program.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit
Change the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-20 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The PROGRAM design menu supports the following options:
B Modify. Change an existing program specication.
B New. Create a new program specication.
B Compile. Compile an existing program.
B Planned_Compile. List the steps necessary to compile and link an
existing program.
B Run. Execute an existing program.
B Drop. Delete an existing program specication.
B Exit. Return to the INFORMIX-4GL menu.
You must rst use the MODULE design menu and the FORMdesign menu to
enter and edit the 4GL statements within the component source-code
modules of a 4GL program. Then you can use the PROGRAMdesign menu to
identify which modules are part of the same application program, and to link
all the modules as an executable command le.
The Modify Option
The Modify option enables you to modify the specication of an existing 4GL
program. (This option is not valid unless at least one program has already
been specied. If none has, you can create a program specication by
choosing the New option from the same menu.)
4GL prompts you for the name of the programspecication to be modied. It
then displays a menu and formthat you can use to update the information in
the program specication database, as shown in Figure 1-2.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-21
The Programmer s Envi ronment
Figure 1-2
Example of a Program Specication Entry
The name of the program appears in the Program eld. In Figure 1-2 the
name is myprog. You can change this name by choosing the Rename option.
4GL assigns the program name, with the extension .4ge, to the executable
programproduced by compiling and linking all the source les and libraries.
(Compiling and linking occurs when you choose the Compile_Options
option, as described on page 1-22.) In this example, the resulting executable
program would have the name myprog.4ge.
Use the 4GL option to update the entries for the 4gl Source elds and the 4gl
Source Pathelds on the form. The ve rows of elds under these labels form
a screen array. When you choose the 4GL option, 4GL executes an INPUT
ARRAY statement so you can move and scroll through the array. See the
INPUT ARRAY statement in Chapter 4, INFORMIX-4GL Statements, for
information about how to use your function keys to scroll, delete rows, and
insert newrows. (You cannot redene the function keys, however, as you can
with a 4GL program.)
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 [ ]
[ ] [ ]
1-22 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The 4GL source program that appears in Figure 1-2 contains three modules:
B One module contains the main program (main.4gl).
B One module contains functions (funct.4gl).
B 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-4GL source modules or object-code
modules in your program. Enter this information into the three-column
screen array with the headings Other Source, Ext, and Other Source Path.
Enter the lename and location of each non-4GL source-code or object-code
module in these elds. Enter the name of the module in the Other Source
eld, the lename extension of the module (for example, ec for an
INFORMIX-ESQL/C module, or c for a C module) in the Ext eld, and the full
directory path of the module in the Other Source Path eld. The example in
Figure 1-2 includes a le containing Cfunction source-code (cfunc.c) located
in /u/john/appl/C. You can list up to 100 les in this array.
The Libraries option enables you to indicate the names of up to ten special
libraries to link with your program. 4GL calls the Ccompiler to do the linking
and adds the appropriate -l prex, so you should enter only what follows the
prex. The example displayed in Figure 1-2 calls only the standard C math
library.
Use the Compile_Options option to indicate up to ten C compiler options.
Enter this information in the Compile Options eld. Do not, however,
specify the -e or -a options of c4gl in this eld, because they will cause the
compilation to fail. (See Creating Programs at the Command Line on
page 1-32 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.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-23
The Programmer s Envi ronment
The New Option
Use the New option on the PROGRAM design menu to create a new
specication of the program modules and libraries that make up an
application program. You can also specify any necessary compiler or loader
options.
The submenu screen forms displayed by the Newand the Modify options of
the PROGRAM design menu are identical, except that you must rst supply
a name for your programwhen you choose the Newoption. (4GL displays a
blank form in the NEW PROGRAM menu.) The NEW PROGRAM menu has
the same options as the MODIFY PROGRAM menu, as illustrated earlier.
The Compile Option
The Compile option performs the compilation and linking described in the
program specication database, taking into account the time when each le
was last updated. It compiles only those les that have not been compiled
since they were last modied.
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, next.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit
Add the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit
Compile a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-24 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Planned_Compile Option
Taking into account the time when the various les in the dependency
relationships last changed, the Planned_Compile option prompts for a
program name and displays a summary of the steps that will be executed if
you choose the Compile option. No compilation actually takes place.
In this instance, changes were made to all the components of the 4GL
program that were listed in Figure 1-2. This display indicates that no
source-code module has been compiled after the program was changed.
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
Compi l i ng INFORMIX- 4GL Source Fi l es 1-25
The Programmer s Envi ronment
The Run Option
The Run option of the PROGRAMdesign menu is the same as the Run option
of the MODULE design menu. It displays a list of any compiled programs
(les with the extension .4ge) and highlights the current program, if a
programhas been specied. 4GL then executes the programthat you choose.
The Drop Option
The Drop option of the PROGRAMdesign menu prompts you for a program
name and removes the compilation and linking denition of that program
from the syspgm4gl database. This action removes the denition only. Your
program and 4GL modules are not removed.
The Exit Option
The Exit option clears the PROGRAM design menu and restores the
INFORMIX-4GL menu.
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit
Execute a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
PROGRAM: Modify New Compile Planned_Compile Run Drop Exit
Drop the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-26 INFORMIX- 4GL Reference Manual
Creati ng Programs i n the Programmers Envi ronment
The QUERY LANGUAGE Menu
The SQL interactive interface is identical to the interactive SQL interface of
INFORMIX-SQL. If you do not have INFORMIX-SQL, 4GL uses the DB-Access
utility. The Query-language option is placedat the top-level menuso youcan
test SQL statements without leaving the 4GL Programmers Environment.
You can also use this option to create, execute, and save SQL scripts.
Creating Programs in the Programmers Environment
To invoke the C Compiler version of the Programmers Environment, enter
the following command at the system prompt:
i4gl
After a sign-on message is displayed, the INFORMIX-4GL menu appears.
To create a 4GL application with the C Compiler version of 4GL
1. Create a new source module or revising an existing source module
2. Compile the source module
3. Link the program modules
4. Execute the compiled program
This process is described in the sections that follow.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-27
Creati ng Programs i n the Programmers Envi ronment
Creating a New Source Module
This section outlines the procedure for creating a newsource module. If your
source module already exists, see Revising an Existing Module, next.
To create a source module
1. Choose the Module option of the INFORMIX-4GL menu.
The MODULE design menu is displayed.
2. If you are creating a new.4gl source module, choose the Newoption
of the MODULE design menu.
3. Enter a name for the new module.
The name must begin with a letter and can include letters, numbers,
and underscores. No more than 10 characters are allowed in this
name, which must be unique among the les in the same directory,
andamong any other modules of the same program. 4GL attaches the
extension .4gl to this lename of your new module.
4. Press RETURN.
Revising an Existing Module
If you are revising an existing 4GL source le, use the following procedure.
To modify a source le
1. Choose 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 choose a source le to edit.
2. Use the arrow keys to highlight the name of a source module and
press RETURN, or enter a lename (with no extension).
If you specied the name of an editor with the DBEDIT environment
variable, an editing session with that editor begins automatically.
Otherwise, the screen prompts you to specify a text editor.
Specify a text editor, or press RETURN for vi, the default editor. Now
you can begin an editing session by entering 4GL statements.
3. When you have nished entering or editing your 4GL code, use an
appropriate editor commandto save your source le andendthe text
editing session.
1-28 INFORMIX- 4GL Reference Manual
Creati ng Programs i n the Programmers Envi ronment
Compiling a Source Module
The .4gl source le module that youcreate or modify is an ASCII le that must
be compiled before it can be executed.
To compile a module
1. Choose the Compile option from the MODULE design menu.
2. Choose the type of module that youare compiling, either Runable or
Object.
If the module is a complete 4GL program that requires no other
modules, choose Runable.
If the module is one module of a multi-module 4GL program, choose
Object. This option creates a compiled object le module, with the
same lename, but with extension .o. See also the next section,
Linking Program Modules.
3. If the compiler detects errors, no compiled le is created, and you are
prompted to x the problem.
Choose Correct to resume the previous text editing session, with the
same 4GL source code, but with error messages in the le. Edit the le
to correct the error, and choose Compile again. If an error message
appears, repeat this process until the module compiles without error.
4. After the module compiles successfully, choose Save-and-exit from
the menu to save the compiled program.
The MODULE design menu appears again on your screen.
5. If your program requires screen forms, choose Form from the
INFORMIX-4GL menu.
The FORM design menu appears. For information about designing
and creating screen forms, see Chapter 6.
6. If your program displays help messages, you must create and
compile a help le.
Use the mkmessage utility to compile the help le. For more infor-
mation on this utility, see Appendix B.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-29
Creati ng Programs i n the Programmers Envi ronment
Linking Program Modules
If your newor modied module is part of a multi-module 4GL program, you
must link all of the modules into a single programle before you can run the
program. If the module that you compiled is the only module in your
program, you are now ready to run your program. (See Executing a
Compiled Program on page 1-31.)
To link modules
1. Choose the Program option from the INFORMIX-4GL menu.
The PROGRAM design menu appears.
2. If you are creating a new multi-module 4GL program, choose the
New option; if you are modifying an existing one, choose Modify.
In either case, the screen prompts you for the name of a program.
3. Enter the name (without a le extension) of the programthat you are
modifying, or the name to be assigned to a new program.
Names must begin with a letter, and can include letters, underscores
( _ ), and numbers. After you enter a valid name, the PROGRAM
screen appears, with your program name in the rst eld.
1-30 INFORMIX- 4GL Reference Manual
Creati ng Programs i n the Programmers Envi ronment
If you chose Modify, the names and pathnames of the source-code
modules are also displayed. In that case, the PROGRAM screen
appears belowthe MODIFY PROGRAMmenu, rather than belowthe
NEW PROGRAM menu. (Both menus list the same options.)
4. Identify the les that make up your program:
B To specify new4GL modules or edit the list of 4GL modules,
choose the 4GL option.
You can enter or edit the name of a module, without the .4gl le
extension. Repeat this step for every module. If the module is not
in the current directory or in a directory specied by the
DBPATH environment variable, enter the pathname to the
directory where the module resides.
B To include any modules in your programthat are not 4GL source
les, choose the Other option.
This option enables you to specify each lename in the Other
Source eld, the lename extension in the Ext eld, and the
pathname in the Other Source Path eld.
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 [ ]
[ ] [ ]
Compi l i ng INFORMIX- 4GL Source Fi l es 1-31
Creati ng Programs i n the Programmers Envi ronment
These elds are part of an array that can specify up to 100 other
modules, such as C language source les or object les. If you
have INFORMIX-ESQL/C installed on your system, you can also
specify ESQL/C source modules (with extension .ec) here.
B To specify any function libraries that should be linked to your
program(besides the 4GL library that is described in Chapter 5,
Built-In Functions and Operators), choose the Libraries
option. This option enables you to enter or edit the list of library
names in the Libraries elds.
B To specify compiler ags, choose the Compile_Options option.
These ags can be entered or edited in the Compile Options
elds.
5. After you have correctly listed all of the modules of your program,
choose the Exit option to return to the PROGRAM design menu.
6. Choose the Compile option of the PROGRAM design menu.
This option produces an executable le that contains all your 4GL
program modules. Its lename is the program name that you
specied, with extension .4ge. The screen lists the names of your .4gl
source modules, and displays the PROGRAMdesign menu with the
Run option highlighted.
Executing a Compiled Program
After compiling and linking your program modules, you can execute your
program. To do so, choose the Run option fromthe MODULE or PROGRAM
design menu. This option begins execution of the compiled 4GL program.
Your program can display menus, screen forms, windows, or other screen
output, according to your programlogic and any keyboard interaction of the
user with the program.
1-32 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Creating Programs at the Command Line
Youcan also create .4gl source les andcompiled.o and.4ge les in makeles
or at the operating systemprompt. Figure 1-3 shows the process of creating,
compiling, linking, and running a 4GL program from the command line.
In Figure 1-3 the rectangles represent processes controlled by specic
commands, and the circles represent les. Arrows indicate whether a le can
serve as input or output (or both) for a process. This diagram is simplied
and ignores the similar processes by which forms, help messages, and other
components of 4GL applications are compiled, linked, and executed. The
diagram outlines the following process:
B The cycle begins in the upper-left corner with a text editor, such as vi,
to produce a 4GL source module.
B A multi-module program can include additional 4GL source les
(.4gl), ESQL/C source les (.ec), C language source les (.c), and
object les (.o).
B The program module can then be compiled by invoking the c4gl
preprocessor and compiler command. (If error messages result, nd
themin the .err le and edit the source le to correct the errors. Then
recompile the corrected source module.)
The resulting compiled .4ge programle is an executable command
le that you can run by entering its name at the system prompt:
filename.4ge
Here lename.4ge species your compiled 4GL le.
Figure 1-3
Creating and
Running a 4GL
Program
. c, . ec
fIles
Text
editor
. 4gl
source
les
. o
object
les
. err
error
le
. 4ge
compiled
program
le
Preprocessor
and compiler
c4gl
Compi l i ng INFORMIX- 4GL Source Fi l es 1-33
Creati ng Programs at the Command Li ne
The following table shows the correspondence between commands and
menu options.
For information on the use of makeles to create 4GL applications, visit the
Informix Developer Network (IDN) on the Web at the following URL:
http://www.informix.com/idn
Creating or Modifying a 4GL Source File
Use your systemeditor or another text editing programto create a .4gl source
le or to modify an existing le. For information on the statements that you
can include in a 4GL program, see Chapter 4.
Compiling a 4GL Module
You can compile a 4GL source le by entering a command of the form:
c4gl source.4gl -o filename.4ge
The c4gl command compiles your 4GL source-code module (here called
source.4gl) and produces an executable program called lename.4ge. The
complete syntax of the c4gl command appears in the next section.
Compiling and Linking Multiple Source Files
A4GL programcaninclude several source-code modules. Youcannot execute
a 4GL program until you have preprocessed and compiled all the source
modules and linked them with any function libraries that they reference.
Menu Option Invokes Command
Module New/Modify UNIX System Editor vi
Compile 4GL Preprocessor/C Compiler c4gl
Run 4GL Application lename.4ge
1-34 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
You can do all this in a single step at the system prompt by using the c4gl
command, which performs the following processing steps:
1. Invokes the i4glc1 preprocessor, which reads your 4GL source-code
les (extension .4gl) and preprocesses them to produce extended
ESQL/C code (extension .4ec).
2. Invokes the i4glc2 preprocessor, which reads the extended ESQL/C
code and preprocesses it to produce ESQL/C code (extension .ec).
3. Invokes the i4glc3 preprocessor, which reads the ESQL/C code and
preprocesses it to produce C code (extension .c).
4. Invokes the i4glc4 preprocessor, which reads the C code and
compiles it to produce an object le (extension .o).
5. Links the object le to the ESQL/C libraries and to any additional
libraries that you specify in the command line.
You must assign the lename extension .4gl to 4GL source-code modules that
you compile. The resulting .4ge le is an executable version of your program.
Tip: The ESQL/C source les (with extension .ec), C source les (with extension .c),
and C object les (with extension .o) are intermediate steps in producing an
executable 4GL program. Besides .4gl source les, you can also include les of any
or all of these types when you specify a c4gl command to compile and link the
component modules of a 4GL program.
Using the c4gl Script for Compilation
For compatibility with Informix database servers, releases of INFORMIX-4GL
must take into account that the database, table, and column names might
contain non-ASCII characters. Most C compilers do not accept these in
variable names, but the i4glc4 process now maps the locale-dependent
characters so that C compilers will accept them.
The Programmers Environment invokes c4gl to do the compilation, using
the -phase option described in the next section. The Programmers
Environment nowruns c4gl -phase 12 (i4glc1 and i4glc2) as its own phase 1,
followed by c4gl -phase 34 (i4glc3 and i4glc4) as its own phase 2, and nally
it runs c4gl -phase 5 (the C compiler) as its own phase 3. Because the c4gl
script is now used for the compilations, however, you can also use the
C4GLFLAGS environment variable (see Appendix D) with the Programmers
Environment. (This is equivalent to the -a option at the command line.)
Compi l i ng INFORMIX- 4GL Source Fi l es 1-35
c4gl Command
c4gl Command
The c4gl command is a shell script that supports the following syntax.
The c4gl commandpasses all Ccompiler arguments (args) andother Csource
and object les (src.c, obj.o) directly to the C compiler (typically cc).
If you omit the -o outle option, the default lename is a.out.
-o outle
-ansi -a -anyerr
source.4gl
obj.o
yourlib
esqlc.ec
src.c
-V
c4gl
-args
-globcurs
-localcurs
-keep
-nokeep
-z -shared
-phase
1 3 4 5 2 -e
-nolinenos
-linenos
-static
-c
Element Description
-args are other arguments for your C compiler.
esql.ec is an ESQL/C source le to compile and link.
obj.o is an object le to link with your 4GL program.
outle is a name that you assign to the compiled 4GL program.
source.4gl is the name of a 4GL source module and its .4gl extension.
src.c is a C language source le to compile and link.
yourlib is a function library other than the 4GL or ESQL/C libraries.
1-36 INFORMIX- 4GL Reference Manual
c4gl Command
You can compile 4GL modules separately fromyour MAIN programblock. If
there is no MAIN program block in source.4gl, your code is compiled to
source.o but is 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. (For more information, see MAIN on page 4-247.) If you
typically compile with the same options, you can set the C4GLFLAGS
environment variable to supply those options implicitly. See the section
C4GLFLAGS on page D-10 for details of this feature.
To display the release version number of your SQL software, use the -V
option. If you specify the -V option, all other arguments are ignored, and no
output les are produced.
The -phase Option
The c4gl compilation command recognizes the ve phases of compilation
and can specify which phases to perform. To perform only the preprocessor
steps, with no compilation or linking, include the -e option.
More generally, the -phase option takes an argument, separated from-phase
by one or more blank spaces. This argument can contain any contiguous
sequence of the positive integers in the range from1 to 5 (that is, 1, 2, 3, 4, 5,
12, 23, 34, 45, 123, 234, 345, 1234, 2345, 12345). These digits specify which
phases of compilation to perform. The -c option implies -phase 12345, and
the -e option implies -phase 1234,.
ANSI Compliance
To instruct the compiler to check all SQL statements for compliance with the
ANSI/ISOstandardfor SQL syntax, include the -ansi option. If youspecify the
-ansi option, it must appear rst inyour list of c4gl commandarguments. The
-ansi option asks for compile-time and runtime warning messages if your
source code includes Informix extensions to the ANSI/ISO standard for SQL.
Compiler warnings and error messages are saved in a le called source.err.
ANSI C compilers generate a warning if line numbers generated from the
compilation are greater than 32767. Line numbers greater than 32767 can
occur in compiled 4GL when the underlying ESQL/C compiler works on a
large program. You can suppress these warnings with the -nolinenos option
of c4gl. You can also explicitly set the default ANSI warnings with the
-linenos option.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-37
c4gl Command
Array Bounds
To have your compiled programcheck array bounds at runtime, include the
-a option, which must appear on the command line before the source.4gl
lename. The -a option requires additional runtime processing, so you might
prefer to use this option only during development to debug your program.
Error Scope
If you specify the -anyerr option, 4GL sets the status variable after evaluating
expressions. The -anyerr option overrides any WHENEVER ERROR state-
ments in your program.
Intermediate Files
When the compilation completes successfully, c4gl automatically removes
the intermediate les with extensions .c, .ec, and .4ec, which are generated
during the rst four phases of compilation. (Some earlier versions of 4GL did
not delete these les.) If the compilation fails or is interrupted, however, all
the intermediate les are left intact.
The -keep option explicitly species that the intermediate les be retained.
The default is the -nokeep option, which species that the intermediate les
be removed. The .o le is retained if you specify the -c ag, but if an
executable is produced, whether the .o le is kept or removed depends on the
C compiler in use. Some compilers keep the .o le, and others remove it
depending on what else you specify on the command line. If you direct c4gl
to do -phase 1234, the .c le is no longer an intermediate le and it is retained.
Similarly, if you request -phase 1, the .4ec les are no longer intermediate
les, and so they are kept.
Informal Functions
The -z option enables c4gl to compile a program that invokes a single
function with a variable number of arguments without i4glc1 giving an error
at compile time.
1-38 INFORMIX- 4GL Reference Manual
c4gl Command
Although fglc supports the -z option, some earlier releases of c4gl ignore the
option, so it is not possible to use the standard script to compile programs
that include such functions. (Most developers should not use this option,
because it suppresses error messages for all functions with variable numbers
of arguments.)
The -globcurs and -localcurs Options
In ESQL/C releases prior to Version 5.00, the scope of reference of names of
cursors and prepared statements is local to a single source code module; the
same name can be reused without conict in different modules. All 4.1x
versions of 4GL used a 4.1x version of ESQL/C. In Version 5.00 and later of
ESQL/C, all cursor and prepared statement names are global by default. Thus
the cursor c_query in lea.ec is the same as the cursor c_query in leb.ec.
To preserve the legacy behavior, the compiler mangles all cursor and
prepared statement names using the same algorithm in both compilers. See
CURSOR_NAME( ) on page 5-52 for the mangling algorithm. (Contact
Informix Technical Support if any pairs of cursor or prepared statement
names are mangled to the same value. The workaround for mangled-name
conicts is to change one of the affected cursor or statement names.)
The -globcurs option makes the names of cursors and of prepared objects
global to the entire program. The compilers still require you to declare the
cursor before using it for any other purpose in the module, so this option is
seldom useful. This option might help in debugging, however, because the
cursor names are not modied.
The -localcurs option can override the -globcurs option if that was set in the
C4GLFLAGS environment variable. The -localcurs optionmakes the names of
cursors and prepared objects local to the module in which they were
declared.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-39
c4gl Command
Using Source Code Debuggers with 4GL Programs
The primary conversion of i4glc4 ensures that the generated C code will
compile when you use 4GL with an NLS or GLS database. In such databases,
the table and column names can contain non-ASCII characters ranging from
128 to 255. You can dene variables using the RECORDLIKE table.* to refer to
these names, but C compilers do not normally allow variable names to
contain such characters. To avoid compilation problems with the Ccompiler,
i4glc4 adjusts the code.
To make the variable names safe, Informix replaces any non-ASCII characters
that occur outside quotedstrings (which only happens in variable or function
names) with a mapped value. For values in the range 0xA0 to 0xFF, Informix
uses the hexadecimal value, printed in uppercase, for the character. The
systemmaps characters in the range 0x80 to 0x8F, to G0 to GF, and values in
the range 0x90 to 0x9F, to H0 to HF. The system converts all ordinary 4GL
identier names to lowercase to avoid a naming conict. By the time this
translation occurs, the names of tables and columns inSQL statements are not
altered; quotation marks protect the names passedto the database server. The
i4glc4 compiler does one other translation, and that only inside strings. It
converts y-umlaut (hex 0xFF) into the escape sequence \377, because some C
compilers are not fully internationalized and read this character as end-of-le.
Using the ESQL/C compiler for phase 3 introduces yet another complication
to the compilation process. 4GL uses a different view of the SQLCA record
fromESQL/C. The warning ags are a series of single characters in ESQL/C,
but 4GL code treats them as a string. The ESQL/C compiler automatically
includes the sqlca.h header ahead of any user-dened code such as the 4GL
declaration of the SQLCA record. This process would lead to two discrepant
denitions of the SQLCA record, and the compilations would fail, unless the
C4GL script handled this. To overcome this problem, i4glc1 emits a line that
starts #define I4GL_SQLCA just before the declaration of the SQLCA record.
The i4glc2 and i4glc3 compilers pass this through. If the .c le to be processed
by i4glc2 contains this denition but does not contain the line #define
SQLCA_INCL, C4GL passes an extra ag to i4glc4 and adds the line #define
SQLCA_INCL in front of the Cle it translates. The Cpreprocessor handles this
so that the contents of the sqlca.h header are ignored, leaving just the 4GL
version of the SQLCA record visible to the C compiler.
1-40 INFORMIX- 4GL Reference Manual
c4gl Command
You can use i4glc4 on its own. It takes the following arguments:
By default, i4glc4 writes the convertedle or les to standardoutput, but you
can overwrite the original le using the -o option; you can back up the
original le with any extension you choose; there is no default le extension.
The i4glc4 compiler automatically inserts a period ( . ) between the name and
the extension. The -o and -s options are mutually exclusive and require a
lename argument. Otherwise, i4glc4 processes any les specied, or
processes standard input if no lenames are provided.
Shared Libraries
Effective with INFORMIX-4GL C Compiler Version 6.0, Informix provides a
shared-library implementation of the 4GL program libraries on many
platforms. The sharedlibrary provides reducedmemory consumption, faster
program start-up, and substantially reduced program le sizes (thereby
saving le system space).
Shared-library support exists for compiled 4GL only. RDS runners (fglgo or
customized runners) are inherently shared because all active users run the
same executable le. This feature is most useful for those installations that
have a variety of compiled 4GL applications. The 4GL library code exists in
only one place in memory and does not have to be added to each 4GL
executable le. On a system with a large number of 4GL programs, the disk
space and memory savings can be substantial.
Informix does not provide a shared-library implementation on all platforms.
On some platforms, shared libraries are not available and on others the
operating system implementation of shared libraries is not compatible with
the Informix code stream.
-V prints version information (does not process any les).
-D emits #define SQLCA_INCL as the rst line of output.
-s ext creates backup le with the extension .ext.
-o overwrites input les.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-41
c4gl Command
To determine if your platform has a shared-library implementation of 4GL,
look at the C4GL help messages. You can display these messages by running
c4gl with no arguments. A help line for the shared option contains one of
these messages:
-shared Use dynamic linking and shared libraries
or:
-shared (Not available on this platform)
If the former message is the one given for your platform, a 4GL shared-library
implementation is provided, and the -shared option is available for your use.
You can demonstrate the memory and le-size savings for your platformby
compiling the 4GL demonstration program (demo4) with and without the
-shared ag, and comparing the outputs of ls and size for each of the
following programs:
B i4gldemo
B c4gl -shared d4_*.4gl -o demo4.shared
B c4gl d4_*.c -o demo4
B ls -l demo4*
B size demo4*
Some platforms provide commands that show the dependencies of a
compiled program on the shared libraries. For instance, on current Sun
platforms, the command is ldd.
For more technical information about shared-library concepts, refer to your
operating system documentation. If your system has man pages (on-line
manuals), the man page for ld might direct you to the appropriate area of
your system documentation.
Using the Shared-Library Facility
To compile a 4GL program for shared-library execution, add the -shared
parameter to your C4GL command line:
c4gl -shared d4_*.4gl -o demo4.shared
1-42 INFORMIX- 4GL Reference Manual
c4gl Command
You must set the -shared parameter explicitly, because the default is -static,
specifying not to use sharedlibraries. If youattempt to use the -sharedoption
on a platformfor which no shared-library support exists, a warning message
is displayed to standard error, and compilation continues with the normal
static libraries.
Many platforms require that dynamically linked (shared-library) programs
be compiled with position-independent code production from the C
compiler. The c4gl script automatically takes care of this for you.
Mixing normal and position-independent code can produce errors. When
you compile with the -shared ag, be sure to recompile all modules fromthe
.4gl source if you had previously compiled any without the -shared ag.
Consider the following example:
c4gl myprog.4gl myutil1.4gl myutil2.4gl -o myprog
c4gl -shared myprog.o myutil1.o myutil2.o -o myprog.shared
Executing this code can produce errors because the objects have not been
compiled with the position-independent option. Alternatively, the following
code is perfectly acceptable, as the myutil objects have been compiled with
position-independent code (if applicable to your platform):
c4gl -shared myprog.4gl myutil1.4gl myutil2.4gl -o
myprog.shared
<change myprog.4gl>
c4gl -shared myprog.4gl myutil1.o myutil2.o -o myprog.shared
Important: For some platforms, the system linker (ld) enforces much stricter name-
collision constraints when you use shared libraries. If you have multiple functions in
your programwith the same name, you might get errors when compiling with shared
libraries even if the programlinks successfully with the static libraries. In such a case,
to eliminate the name collision you need to rename one of the functions.
Technical Details
The name and location of the 4GL shared library varies depending on the
version of 4GL you are using, the naming convention for shared libraries on
your platform, and the ability of the linker on your platformto locate shared
libraries in nonstandard directories. The name of the shared library begins
with lib4gsh and continues with a three-digit version indicator (for example,
604 for the 6.04 release). The sufx is platform dependent; common values
are .so and .a.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-43
c4gl Command
In most cases, the 4GL shared library resides with the other 4GL libraries in
the $INFORMIXDIR/lib/tools directory. If your platform does not allow
shared libraries in nonstandard directories, your systemadministrator might
have to copy the library to a standard system directory such as /lib or
/usr/lib. Look in the machine-specic notes for your platformto see if this is
necessary. Most, if not all, platforms require that any programs that change
their user ID dynamically while running (often referred to as setuid programs)
and use shared libraries can only access those shared libraries in standard
systemdirectories. Therefore, if you have a setuid 4GL programthat uses the
4GL shared library, your system administrator must copy or link the 4GL
shared library to a standard directory.
Runtime Requirements
Unlike static-linked 4GL programs, 4GL programs that use the shared library
must have access to that library at runtime. Most platforms provide an
environment variable that instructs the linking program loader of the
operating system to add one or more nonstandard directories to its shared-
library search list. Common examples of this variable are
LD_LIBRARY_PATH, LPATH, or SHLIB_PATH. The machine-specic notes
provided with 4GL contain the appropriate variable name for your platform.
To run your shared-library 4GL applications, you must have this variable set
properly in its shell environments. For example:
Bourne or Korn Shells
LD_LIBRARY_PATH=$INFORMIXDIR/lib/tools
export LD_LIBRARY_PATH
C Shell Variants
setenv LD_LIBRARY_PATH ${INFORMIXDIR}/lib/tools
Be sure that all potential users set their environments accordingly or update
global environment scripts as applicable for their site.
If you develop 4GL applications that are sent out to other systems, the shared
library must be available to those systems also. All platforms that have 4GL
shared-library support also have the 4GL shared library included in corre-
sponding runtime versions of 4GL. Be sure to notify your remote users and
runtime customers of these environment variable needs.
1-44 INFORMIX- 4GL Reference Manual
c4gl Command
Compiling with c4gl
The simplest case is to compile a single-module 4GL program. The following
command produces an executable program called single.4ge:
c4gl single.4gl -o single.4ge
In the next example, the object les mod1.o, mod2.o, and mod3.o are
previously compiled 4GL modules, and mod4.4gl is a source-code module.
Suppose that you wish to compile and link mod4.4gl with the three object
modules to create an executable programcalled myappl.4ge. To do so, enter
the following command line:
c4gl mod1.o mod2.o mod3.o mod4.4gl -o myappl.4ge
Invoking a Compiled 4GL Program at the Command Line
As noted in the previous section, a valid c4gl command line produces a .4ge
le (or whatever you specify after the -o argument) that is an executable
command le. To execute your compiled 4GL application program, enter the
executable lename at the system prompt.
For example, to run myappl.4ge (the program in the previous example),
enter the following command:
myappl.4ge
Some 4GL programs might require additional command-line arguments,
such as arguments or lenames, depending on the logic of your application.
See the descriptions of the built-in functions ARG_VAL( ) on page 5-18 and
NUM_ARGS( ) on page 5-93, which can return individual command-line
arguments (and the number of command-line arguments) to a calling context
within the 4GL application.
No special procedures are needed to create, compile, or execute programs
that call C or ESQL/C functions when you use the C Compiler implemen-
tation of 4GL. For more information, see Appendix C, Using C with
INFORMIX-4GL.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-45
Program Fi l ename Extensi ons
Program Filename Extensions
Source, executable, error, and backup les generated by 4GL are stored in the
current directory and are labeled with a lename extension. The following
list shows the le extensions for the source, runable, and error les. These
les are produced during the normal course of using the C Compiler.
The last three les do not exist unless you create or modify a screen form
specication le, as described in Chapter 6, Screen Forms.
Under normal conditions, 4GL also creates certain backup les and
intermediate les as necessary and deletes them when a compilation is
successful. If something interrupts a compilation, however, you
might nd one or more of these backup or intermediate les in your
current directory. For more information, see Intermediate Files on
page 1-37.
Warning: INFORMIX-4GL is not designed to support two or more programmers
working concurrently in the same directory. If several developers are working on the
same 4GL application, make sure that they do their work in different directories.
File Description
le.4gl 4GL source le.
le.o 4GL object le.
le.4ge 4GL executable (runable) le.
le.per FORM4GL source le.
le.frm FORM4GL object le.
le.err FORM4GL source error le.
1-46 INFORMIX- 4GL Reference Manual
Program Fi l ename Extensi ons
The following table identies some backup and intermediate les that can be
produced when you compile 4GL code to C code from the Programmers
Environment.
During the compilation process, 4GL stores a backup copy of the le.4gl
source le in le.4bl. The time stamp is modied on the (original) le.4gl
source le, but not on the backup le.4bl le. In the event of a system crash,
you might need to replace the modied le.4gl le with the backup copy
contained in the le.4bl le.
The Programmers Environment does not allow you to begin modifying a
.4gl or .per source le if the corresponding backup le already exists in the
same directory. After an editing session terminates abnormally, for example,
you must delete or rename any backup le before you can resume editing
your 4GL module or form from the Programmers Environment.
File Description
le.4bl 4GL source backup le, created during modication and compilation of
.4gl program modules
le.4bo Object backup le, created during compilation of .o program modules
le.4be Object backup le, created during compilation of .4ge programmodules
le.err 4GLsource error le, createdwhenanattempt to compile a module fails.
The le contains 4GL source code, as well as any compiler syntax error
or warning messages.
le.ec Intermediate source le, created during the normal course of compiling
a 4GL module.
le.c Intermediate C le, created during the normal course of compiling a
4GL module.
le.erc 4GL object error le, created when an attempt to compile or to link a
non-4GL source-code or object module fails. The le contains 4GL
source code and annotated compiler errors.
le.4ec Intermediate output of the i4glc1 preprocessor, containing extended
ESQL/C statements as input for the i4glc2 preprocessor.
le.pbr FORM4GL source backup le
le.fbm FORM4GL object backup le
Compi l i ng INFORMIX- 4GL Source Fi l es 1-47
The Rapi d Devel opment System
The Rapid Development System
This section describes the following aspects of the Rapid Development
System version of 4GL:
B All the menu options and screen form elds of the RDS
Programmers Environment
B The steps for compiling andexecuting 4GL programs fromthe menus
of the Programmers Environment
B The equivalent command-line syntax
B The lename extensions of 4GL source-code, object, error, and
backup les
The Programmers Environment
The Rapid Development System provides a series of menus called the
Programmers Environment. These menus support the steps of 4GL program
development and keep track of the components of your application. You can
invoke the Programmers Environment by entering r4gl at the system
prompt.
The INFORMIX-4GL Menu
The r4gl command briey displays the INFORMIX-4GL banner and sign-on
message. The INFORMIX-4GL menu appears.
INFORMIX-4GL: Module Form Program Query-language Exit
Create, modify or run individual 4GL program modules.
-------------------------------------------------Press CTRL-W for Help------
1-48 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
This is the highest menu, from which you can reach any other menu of the
Programmers Environment. You have ve options:
B Module. Work on an INFORMIX-4GL program module.
B Form. Work on a screen form.
B Program. Specify components of a multi-module program.
B Query-language. Use an SQL interactive interface, if you have either
INFORMIX-SQL or DB-Access installed on your system. (See the
documentation of these Informix products for details of their use.)
B Exit. Return to the operating system.
The rst three options display newmenus that are describedin the pages that
follow. (You can also press CONTROL-Wat any menu to display an on-line help
message that describes your options.) As at any 4GL menu, you can choose
an option in either of two ways:
B By typing the rst letter of the option.
B By using the SPACEBAR or arrow keys to move the highlight to the
option that you choose, and then pressing RETURN.
The MODULE Design Menu
You can press RETURN or type m or M to choose the Module option of the
INFORMIX-4GL menu. This option displays a newmenu, calledthe MODULE
design menu. Use this menu to work on an individual 4GL source-code le.
MODULE: Modify New Compile Program_Compile Run Debug Exit
Change an existing 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-49
The Programmer s Envi ronment
The MODULE design menu supports the following options:
B Modify. Change an existing 4GL source-code module.
B New. Create a new4GL source-code module.
B Compile. Compile an existing 4GL source-code module.
B Program_Compile. Compile a 4GL application program.
B Run. Execute a compiled 4GL module or multi-module application
program.
B Debug. Invoke the INFORMIX-4GL Interactive Debugger to examine
an existing 4GL programmodule or application program(if youhave
the Debugger product installed on your system).
B Exit. Return to the INFORMIX-4GL menu.
As in all of the menus of the Programmers Environment except for the
INFORMIX-4GL menu, the Exit option returns control to the higher menu
from which you accessed the current menu (or, when you choose Exit from
the INFORMIX-4GL menu, terminates the 4GL session and returns to the
system prompt).
You can use these options to create and compile source-code modules of a
4GL application. (For information on creating 4GL screen forms, see The
FORM Design Menu on page 1-54. For information on creating and
compiling programmer-dened help messages for a 4GL application, see the
description of the mkmessage utility in Appendix B.)
The Modify Option
Choose this option to edit an existing 4GL source-code module. You are
prompted for the name of the 4GL source-code le to modify and the text
editor to use. If you have designated a default editor with the DBEDIT
environment variable (see Appendix D, Environment Variables) or named
an editor previously in this session at the Programmers Environment, 4GL
invokes that editor. The .4gl source le whose lename you specied is the
current le.
1-50 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
When you leave the editor, 4GL displays the MODIFY MODULE menu, with
the Compile option highlighted.
If you press RETURN or type c or C to choose the Compile option, 4GL displays
the COMPILE MODULE menu.
The Object option creates a le with a .4go extension. The Runable option
creates a le with a .4gi extension. Choose the Runable option if the current
programmodule is a stand-alone 4GL program. If this is not the case (that is,
if the le is one of several 4GL source-code modules within a multi-module
program), you should use the Object option instead, and you must use the
PROGRAM design menu to specify all the component modules.
After you choose Object or Runable, a message near the bottomof the screen
advises you if 4GL issues a compile-time warning or error. If there are
warnings (but no errors), a p-code le is produced. Choose the Exit option of
the next menu, andthenSave-and-exit at the MODIFYMODULE menu, if you
prefer to save the p-code le without reading the warnings.
Alternatively, you can examine the warning messages by choosing Correct at
the next menu. When you nish editing the .err le that contains the
warnings, you must choose Compile again from the MODIFY MODULE
menu, because the Correct option deletes the p-code le.
MODIFY MODULE: Compile Save-and-exit Discard-and-exit
Compile the 4GL module specification.
-------------------------------------------------Press CTRL-W for Help------
COMPILE MODULE: Object Runable Exit
Create object file (.4go suffix).
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-51
The Programmer s Envi ronment
If there are compilation errors, the following menu appears.
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, because 4GL does this for you.) Correct your source le, save
your changes, and exit from the editor. The MODIFY MODULE menu
reappears, prompting you to recompile, 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 choose this option, 4GL saves
the current source-code module as a disk le with the lename extension .4gl,
and saves the compiled version as a le with the same lename, but with the
extension .4go or .4gi. If you choose the Discard-and-Exit option, 4GL
discards any changes that were made to your le after you chose the Modify
option.
The New Option
Choose this option to create a new4GL source-code module.
COMPILE MODULE: Correct Exit
Correct errors in the 4GL module.
-------------------------------------------------Press CTRL-W for Help------
MODULE: Modify New Compile Program_Compile Run Debug Exit
Create a new 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
1-52 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The New option resembles the Modify option, but NEW MODULE is the
menu title, and you must enter a new module name, rather than choose it
froma list. If you have not designated an editor previously in this session or
with DBEDIT, you are prompted for the name of an editor. Then an editing
session begins.
The Compile Option
The Compile option enables you to compile an individual 4GL source-code
module without rst choosing the Modify option.
After you specify the name of a 4GL source-code module to compile, the
screen displays the COMPILE MODULE menu. For information on the
COMPILE MODULE menu options, see The Modify Option on page 1-49.
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 The Compile
Option onpage 1-64). The Program_Compile optionenables youto compile
and combine modules as described in the program specication database,
taking into account the time when the modules were last updated. This
option is useful when you have just modied a single module of a complex
program and wish to test it by compiling it with the other modules.
MODULE: Modify New Compile Program_Compile Run Debug Exit
Compile an existing 4GL program module.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-53
The Programmer s Envi ronment
The Run Option
Choose this option to begin execution of a compiled program.
The RUN PROGRAM screen presents a list of compiled modules and
programs, with the highlight on the module corresponding to the current le,
if any has been specied. Compiled programs must have the extension .4gi
to be included in the list. If you compile a module with the extension .4go,
you can run it by typing the lename and extension at the prompt. If no
compiled programs exist, 4GL displays an error message and restores the
MODULE design menu.
The Debug Option
Choose this option to use the Debugger to analyze a program. This option is
implemented only if you have separately purchased and installed the
Debugger on your system.
If you have the Debugger product, refer to the Guide to the INFORMIX-4GL
Interactive Debugger for more information about this option.
MODULE: Modify New Compile Program_Compile Run Debug Exit
Execute an existing 4GL program module or application program.
-------------------------------------------------Press CTRL-W for Help------
MODULE: Modify New Compile Program_Compile Run Debug Exit
Returns to the INFORMIX-4GL menu.
-------------------------------------------------Press CTRL-W for Help------
1-54 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Exit Option
Choose this option to exit from the MODULE design menu and display the
INFORMIX-4GL menu.
The FORM Design Menu
You can type f or F at the INFORMIX-4GL menu to choose the Form option.
This option replaces the INFORMIX-4GL menu with a new menu, called the
FORM design menu.
You can use this menu to create, modify, and compile screen form specica-
tions. These specications dene visual displays that 4GL applications can
use to query and modify the information in a database. 4GL screen form
specications are ASCII les that are described in Chapter 6.
MODULE: Modify New Compile Program_Compile Run Debug Exit
Returns to the INFORMIX-4GL menu.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Change an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-55
The Programmer s Envi ronment
The FORM design menu supports the following options:
B Modify. Change an existing 4GL screen form specication.
B Generate. Create a default 4GL screen form specication.
B New. Create a new4GL screen form specication.
B Compile. Compile an existing 4GL screen form specication.
B Exit. Return to the INFORMIX-4GL menu.
If you are familiar with the menu systemof INFORMIX-SQL, you might notice
that this menu resembles the menu displayed by the Form option of the
INFORMIX-SQL main menu.
For descriptions of the usage and statement syntax of 4GL screen form
specications, see Chapter 6.
The Modify Option
The Modify option of the FORMdesign menu enables you to edit an existing
formspecication le. It resembles the Modify option in the MODULE design
menu because both options are used to edit program modules.
If you choose this option, you are prompted to choose the name of a form
specication le to modify. Source les created at the FORMdesign menu (or
at the command line by the form4gl screen form facility) have the le
extension .per.
FORM: Modify Generate New Compile Exit
Change an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
1-56 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
If you have not already designated a text editor in this 4GL session or with
DBEDIT, you are prompted for the name of an editor. Then an editing session
begins, with the form specication source-code le that you specied as the
current le. When you leave the editor, 4GL displays the MODIFY FORM
menu with the Compile option highlighted.
Now you can press RETURN to compile the revised form specication le. If
the compiler nds errors, the COMPILE FORM menu appears.
Press RETURN to choose 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. 4GL deletes these messages when you save the
edited le and exit fromthe 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 to either save the
modied form specication le and the compiled form, or discard the
changes. (Discarding the changes restores the version of your form
specications from immediately before you chose the Modify option.)
MODIFY FORM: Compile Save-and-exit Discard-and-exit
Compile the form specification.
-------------------------------------------------Press CTRL-W for Help------
COMPILE FORM: Correct Exit
Correct errors in the form specification.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-57
The Programmer s Envi ronment
The Generate Option
You can type g or G to choose the Generate option. This option creates a
simple default screen formfor use directly in your 4GL program, or for you to
edit later by choosing the Modify option.
When you choose this option, 4GL prompts you to choose a database, to
choose a lename for the formspecication, andto identify the tables that the
form will access. After you provide this information, 4GL creates and
compiles a form specication le. This process is equivalent to running the -
d (default) option of the form4gl command, as described in Compiling a
Form at the Command Line on page 6-88.
The New Option
The Newoption of the FORMdesign menuenables youto create a newscreen
form specication.
After prompting you for the name of your formspecication le, 4GL places
you in the editor where you can create a form specication le. When you
leave the editor, 4GL transfers you to the NEW FORM menu that is like the
MODIFY FORMmenu. You can compile your formand correct it in the same
way.
FORM: Modify Generate New Compile Exit
Generate and compile a default form specification.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Create a new form specification.
-------------------------------------------------Press CTRL-W for Help------
1-58 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Compile Option
The Compile option enables you to compile an existing form specication
le without going through the Modify option.
4GL prompts you for the name of the form specication le and then
performs the compilation. If the compilation is not successful, 4GL displays
the COMPILE FORM menu with the Correct option highlighted.
The Exit Option
The Exit option clears the FORM design menu from the screen.
FORM: Modify Generate New Compile Exit
Compile an existing form specification.
-------------------------------------------------Press CTRL-W for Help------
FORM: Modify Generate New Compile Exit
Returns to the INFORMIX-4GL menu.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-59
The Programmer s Envi ronment
Choosing this option restores the INFORMIX-4GL menu.
The PROGRAM Design Menu
A 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 a 4GL program that
includes several modules. The INFORMIX-4GL menu includes the Program
option so that you can create multiple-module programs. When you choose
this option, 4GL searches your DBPATH directories (as described in
Appendix D) for the program design database, called syspgm4gl. This
database stores the names of objects that are used to create 4GL programs,
and their build dependencies.
If 4GL cannot nd this database, you are asked if you want one created. If you
enter y in response, 4GL creates the syspgm4gl database, grants CONNECT
privileges to PUBLIC, and displays the PROGRAMdesign menu. As Database
Administrator of syspgm4gl, you can later restrict the access of other users.
If syspgm4gl already exists, the PROGRAM design menu appears.
You can use this menu to create or modify a multi-module 4GL program
specication, or to compile, execute, or analyze a program.
INFORMIX-4GL: Module Form Program Query-language Exit
Create, modify or run individual 4GL program modules.
-------------------------------------------------Press CTRL-W for Help------
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Change the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-60 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The PROGRAM design menu supports the following eight options:
B Modify. Change an existing program specication.
B New. Create a new program specication.
B Compile. Compile an existing program.
B Planned_Compile. Display the steps to compile an existing
program.
B Run. Execute an existing program.
B Debug. Invoke the Debugger.
B Undene. Delete an existing program specication.
B Exit. Return to the INFORMIX-4GL menu.
You must rst use the MODULE design menu and FORM design menu to
enter and edit the 4GL statements within the component source-code
modules of a 4GL program. Then you can use the PROGRAMdesign menu to
identify which modules are part of the same application program, and to
combine all the 4GL modules in an executable program.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-61
The Programmer s Envi ronment
The Modify Option
The Modify option enables you to modify the specication of an existing 4GL
program. (This option is not valid unless at least one program has already
been specied. If none has, you can create a program specication by
choosing the New option from the same menu.) 4GL prompts you for the
name of the program specication that you wish to modify. It then displays
a screen and menu that you can use to update the information in the program
specication database, as shown in Figure 1-4.
The name of the program appears in the Program eld. In Figure 1-4 this
name is myprog. You can change the name by choosing the Rename option.
The programname, with extension .4gi, is assigned to the programproduced
by compiling and combining all the source les. (Compiling and combining
occurs when you choose the Compile option, as described in The Compile
Option on page 1-64, or the Program_Compile option of the MODULE
design menu.) In this case, the runable program would have the name
myprog.4gi.
Figure 1-4
Example of a
Program
Specication Entry
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 ] [ ]
[ ] [ ]
1-62 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The 4GL option enables you to update the entries for the 4gl Source and 4gl
Source Path elds. The ve rows of elds under these labels form a screen
array. If you choose the 4GL option, 4GL executes an INPUT ARRAY statement
so that you can move through the array and scroll for up to a maximum of
100 entries.
The INPUT ARRAY statement description in Chapter 4 explains how to use
function keys to scroll, delete rows, and insert new rows. (You cannot
redene function keys, however, as you can with a 4GL program.)
In the example shown in Figure 1-4, the 4GL source programhas been broken
into three modules:
B One module contains the main program (main.4gl).
B One module contains functions (funct.4gl).
B One module contains REPORT statements (rept.4gl).
These modules are all located in the directory /u/john/appl/4GL. If a module
contains only global variables, you can list it here or in the Global Source
array.
The Globals option enables you to update the Global Source array. If you use
the Global Source array to store a globals module, any modication of the
globals module le causes all 4GL modules to be recompiled when you
choose the Compile option.
The Other option enables you to update the entries for the Other .4go and
Other .4go Path elds. This is where you specify the name and location of
other 4GL object les (.4go les) to include in your program. Do not specify
the lename extensions. You can list up to 100 les in this array.
The Program_Runner option enables you to specify the name and location of
the p-code runner to execute your program. You can run 4GL programs with
fglgo (the default) or with a customized p-code runner. A customized p-code
runner is an executable programthat you create to run 4GL programs that call
Cfunctions. (See RDS Programs That Call CFunctions onpage 1-79.) If you
do not modify the Runner eld, your program is executed by fglgo when
you choose the Run option from the PROGRAM design menu.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-63
The Programmer s Envi ronment
The MODIFY PROGRAM screen form contains two additional elds labeled
Debugger and Debugger Path. If you have the Debugger, you can also use
the Program_Runner option to enter the name of a customizeddebugger. See
RDS Programs That Call C Functions on page 1-79 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.
The New Option
The Newoption of the PROGRAMdesign menu enables you to create a new
specication of the programmodules and libraries that make up the desired
application program.
The lename of the module must be unique among source-code modules of
the same 4GL program, and can include up to ten characters, not including
the .4gl le extension. The New option is identical to the Modify option,
except that youmust rst supply a name for your program. 4GL then displays
a blank formwith a NEW PROGRAMmenu that has the same options as the
MODIFY PROGRAM menu.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Add the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-64 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Compile Option
The Compile option compiles and combines the modules listed in the
programspecication database, taking into account the time when les were
last updated. 4GL compiles only those les that have been modiedafter they
were last compiled, except in the case where you have modied a module
listed in the Global Source array. In that case, all les are recompiled.
The Compile option produces a runable p-code le with a .4gi extension. 4GL
lists each step of the compilation as it occurs.
The Planned_Compile Option
Taking into account the time of last change for the various les in the
dependency relationships, the Planned_Compile option prompts for a
program name and displays a summary of the steps that will be executed if
you choose Compile. No compilation actually takes place.
If you have made changes in all the components of the program listed in
Figure 1-4 on page 1-61 since the last time that they were compiled, 4GL
displays the previous screen.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Compile a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
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
Compi l i ng INFORMIX- 4GL Source Fi l es 1-65
The Programmer s Envi ronment
The Run Option
Choose the Run option to execute a compiled program.
The screen lists any compiled programs (les with the extension .4gi) and
highlights the current program, if one has been specied. This option
resembles the Run option of the MODULE design menu.
Although .4go les are not displayed, you can also enter the name and
extension of a .4go le. Whatever compiled programyou choose is executed
by fglgo or by the runner that you specied in the Runner eld of the
Program Specication screen. This screen was illustrated earlier, in the
description of the MODIFY PROGRAM menu.
The Debug Option
The Debug option works like the Run option but enables you to examine a
4GL programwith the Debugger. This option is not implemented unless you
have purchased the Debugger.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Execute a 4GL application program
-------------------------------------------------Press CTRL-W for Help------
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Drop the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
1-66 INFORMIX- 4GL Reference Manual
The Programmer s Envi ronment
The Undene Option
The Undene option of the PROGRAM design menu prompts you for a
programname and removes the compilation denition of that programfrom
the syspgm4gl database. This action removes the denition only. Your
program and 4GL modules are not removed.
The Exit Option
The Exit option clears the PROGRAM design menu from the screen and
restores the INFORMIX-4GL menu.
The QUERY LANGUAGE Menu
The SQL interactive interface is identical to the interactive SQL interface
of INFORMIX-SQL, if you have separately purchased and installed the
INFORMIX-SQL product on your system. If you have not, this option invokes
the DB-Access utility, which is provided with some Informix databases, if 4GL
can locate the executable DB-Access le.
The Query-language option is placed at the top-level menu so that you can
test SQL statements without leaving the Programmers Environment. Youcan
also use this option to create, execute, and save SQL scripts.
PROGRAM: Modify New Compile Planned_Compile Run Debug Undefine Exit
Drop the compilation definition of a 4GL application program.
-------------------------------------------------Press CTRL-W for Help------
Compi l i ng INFORMIX- 4GL Source Fi l es 1-67
Creati ng Programs i n the Programmers Envi ronment
Creating Programs in the Programmers Environment
Enter the following command at the system prompt to invoke the
Programmers Environment:
r4gl
After a sign-on message, the INFORMIX-4GL menu appears.
Creating a 4GL application with the Rapid Development Systemrequires the
following steps:
1. Creating a newsource module or revising an existing source module
2. Compiling the source module
3. Linking the program modules
4. Executing the compiled program
This process is described in the sections that follow.
Creating a New Source Module
This section outlines the procedure for creating a newmodule. If your source
module already exists but needs to be modied, skip ahead to the next
section, Revising an Existing Module.
To create a source module
1. Choose the Module option of the INFORMIX-4GL menu by pressing
M or by pressing RETURN.
The MODULE design menu is displayed.
2. If you are creating a new .4gl source module, press N to choose the
New option of the MODULE design menu.
3. Enter a name for the new module.
The name must begin with a letter, and can include letters, numbers,
and underscores. The name must be unique among the les in the
same directory, and among the other program modules, if it will be
part of a multi-module program. 4GL attaches the extension .4gl to
this identier, as the lename of your new source module.
4. Press RETURN.
1-68 INFORMIX- 4GL Reference Manual
Creati ng Programs i n the Programmers Envi ronment
Revising an Existing Module
If you are revising an existing 4GL source le, use the following procedure.
To modify a source le
1. Choose 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 choose a source le to edit.
2. Use the arrow keys to highlight the name of a source module and
press RETURN, or enter a lename (with no extension).
If you specied a default editor with the DBEDIT environment
variable, an editing session begins automatically. Otherwise, the
screen prompts you to specify a text editor.
Specify the name of a text editor, or press RETURN for vi, the default
editor. Now you can begin an editing session by entering 4GL state-
ments. (Chapters that follow describe 4GL statements and
expressions, as well as built-in functions and operators.)
3. When you have nished entering or editing your 4GL code, use an
appropriate editor commandto save your source le andendthe text
editing session.
Compiling a Source Module
The .4gl source le module that youcreate or modify is an ASCII le that must
be compiled before it can be executed.
To compile a module
1. Choose the Compile option from the MODULE design menu.
2. Select the type of module that you are compiling, either Object or
Runable.
If the module is a complete 4GL program that requires no other
modules, choose Runable. This option creates a compiled p-code
version of your program module, with the same lename, but with
the extension .4gi.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-69
Creati ng Programs i n the Programmers Envi ronment
If the module is one module of a multi-module 4GL program, choose
Object. This creates a compiled p-code version of your program
module, with the same lename, but with the extension .4go. For
more information, see Combining ProgramModules on page 1-69.
3. If the compiler detects errors, no compiled le is created, and you are
prompted to x the problem.
Choose Correct to resume the previous text editing session, with the
same 4GL source code, but with error messages in the le. Edit the le
to correct the error, and choose Compile again. If an error message
appears, repeat this process until the module compiles without error.
4. After the module compiles successfully, choose Save-and-exit from
the menu to save the compiled program.
The MODULE design menu appears again on your screen.
5. If your program requires screen forms, choose Form from the
INFORMIX-4GL menu to display the FORM design menu. For infor-
mation about designing and creating screen forms, see Chapter 6.
6. If your program displays help messages, you must create and
compile a help le.
Use the mkmessage utility to compile the le. For more information
about this utility, see Appendix B.
Important: This version of the runner or Debugger cannot interpret programs
compiled to p-code by releases of 4GL earlier than Version 7.30. You must rst
recompile your source les and form specications. Similarly, releases of the 4GL
runner or Debugger earlier than Version 7.30 cannot interpret p-code that this
release produces.
Combining Program Modules
If your newor modied module is part of a multi-module 4GL program, you
must combine all of the modules into a single programle before you can run
the program. If the module that you compiled is the only module in your
program, youare nowready to runyour program. (For more information, see
Executing a Compiled RDS Program on page 1-71.)
1-70 INFORMIX- 4GL Reference Manual
Creati ng Programs i n the Programmers Envi ronment
To combine modules
1. Choose the Program option from the INFORMIX-4GL menu.
The PROGRAM design menu appears.
2. If you are creating a new multi-module 4GL program, choose the
New option; if you are modifying an existing one, choose Modify.
In either case, the screen prompts you for the name of a program.
3. Enter the name (without a le extension) of the programthat you are
modifying, or the name to be assigned to a new program.
Names must begin with a letter, and can include letters, underscores
( _ ) symbols, and numbers. After you enter a valid name, the
PROGRAMscreen appears, with your programname in the rst eld.
If you chose Modify, the names and pathnames of the source-code
modules are also displayed. The PROGRAMscreenappears belowthe
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
[ ] [ ]
[ ] [ ]
Compi l i ng INFORMIX- 4GL Source Fi l es 1-71
Creati ng Programs i n the Programmers Envi ronment
4. Identify the les that make up your program:
B To specify new4GL modules or edit the list of 4GL modules,
choose the 4GL option.
You can enter or edit the name of a module under the heading
4GL Source; the .4gl le extension is optional. Repeat this stepfor
every module. If the module is not in the current directory or in
a directory specied by the DBPATHenvironment variable, enter
the pathname to the directory where the module resides.
The name of the runner (and of the Debugger, if you have the
Debugger) are usually as illustrated in the PROGRAM screen,
unless your 4GL program calls C functions. For information on
calling C functions, see RDS Programs That Call C Functions
on page 1-79.
B To enter or edit the name or pathname of a Globals module,
choose the Globals option and provide the corresponding
information.
B To enter or edit the le or pathname of any .4go modules that
you have already compiled, choose the Other option.
5. After you correctly list all of the modules of your 4GL program,
choose the Exit option to return to the PROGRAM design menu.
6. Choose the Compile option of the PROGRAM design menu.
This option produces a le that combines all of your .4gl source les
into an executable program. Its lename is the program name that
you specied, with extension .4gi. The screen lists the names of your
.4gl source modules and displays the PROGRAMdesign menu with
the Run option highlighted.
Executing a Compiled RDS Program
After compiling your program modules, you can execute your program. To
do so, choose the Run option from the MODULE design menu. This option
executes the compiled 4GL program.
Menus, screen forms, windows, or other screen output are displayed,
according to your program logic and the keyboard interaction of the user
with the program.
1-72 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Invoking the Debugger
If you are developing or modifying a 4GL program, you have much greater
control over program execution by rst invoking the Debugger. If you have
purchased the Debugger, you can invoke it fromthe MODULE design menu
or PROGRAM design menu of the Programmers Environment by choosing
the Debug option. For information on using the Debugger, see the Guide to
the INFORMIX-4GL Interactive Debugger.
Creating Programs at the Command Line
You can also create .4gl source les and compiled .4go and .4gi p-code les at
the operating system prompt. Figure 1-5 shows the commands for creating,
compiling, and running or debugging a single-module program.
In Figure 1-5, the rectangles represent processes controlled by specic
commands, and the circles represent les. Arrows indicate whether a le
serves as input or output for a process.
(For the sequence of operating systemcommands to create multi-module 4GL
programs, see Figure 1-6 on page 1-76.)
Figure 1-5
Creating and Running a
Single-Module Program
Text
editor
. 4gl
source
le
. 4go
compiled
p-code
le
P-code
runner
fglgo
P-code
compiler
fglpc
Debugger
fgldb
Compi l i ng INFORMIX- 4GL Source Fi l es 1-73
Creati ng Programs at the Command Li ne
This diagramis simplied and ignores the similar processes by which forms,
help messages, and any other components of 4GL applications are compiled
and executed. The diagram outlines the following process:
B The cycle begins in the upper-left corner with a text editor, such as vi,
to produce a 4GL source module.
B The program module can then be compiled, using the fglpc p-code
compiler. (If error messages are produced by the compiler, nd them
in the .err le, and edit the .4gl le to correct the errors. Then
recompile the corrected .4gl le.)
B The following command line invokes the p-code runner:
fglgo filename
where lename species a compiled 4GL le to be executed.
Executing a program that is undergoing development or modication
sometimes reveals the existence of runtime errors. If you have licensed the
Debugger, you can invoke it to analyze and identify runtime errors in your
program by entering the command:
fgldb filename
where lename species your compiled 4GL le. You can then recompile and
retest the program. When it is ready for use by others, they can use the fglgo
runner to execute the compiled program.
A correspondence between commands and menu options of the RDS
Programmers Environment is summarized by the following list.
Subsequent sections of this chapter describe how to use the Rapid Devel-
opment System to compile and execute 4GL programs that call C functions.
(This requires a C language compiler and linker, which are unnecessary for
4GL applications in p-code that do not call programmer-dened Cfunctions.)
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
1-74 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Creating or Modifying a 4GL Source File
Use your systemeditor or another text-editing programto create a .4gl source
le, or to modify an existing le. For information on the statements that you
can include in a 4GL program, see Chapter 4.
Compiling an RDS Source File
You cannot execute a 4GL program until you compile each source module
into a .4go le. Do this at the systemprompt by entering the fglpc command,
which compiles your 4GL source code and generates a le containing tables
of information and blocks of p-code. You can then run this compiled code by
using the 4GL p-code runner (or the Debugger if you have it). The 4GL source-
code module to be compiled should have the le extension .4gl.
fglpc Command
The fglpc command supports the following syntax.
The fglpc command reads source.4gl les and creates a compiled version of
each, with the lename source.4go. You can specify any number of source
les, in any order, with or without their .4gl lename extensions.
-localcurs
-ansi -globcurs
fglpc
-p pathname
.4gl
-V
source
-anyerr -a
Element Description
pathname is the pathname of a directory to hold object and error les.
source is the name of a 4GL source module. The .4gl extension is optional.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-75
Creati ng Programs at the Command Li ne
To instruct the compiler to check all SQL statements for compliance with the
ANSI/ISO standard for SQL, use the -ansi option. If you specify the -ansi
option, it must appear rst among fglpc command arguments. Including the
-ansi option asks for compile-time and runtime warning messages if your
source code includes Informix extensions to the ANSI/ISO standard for SQL.
If an error or warning occurs during compilation, 4GL creates a le called
source.err. Look in source.err to nd where the error or warning occurred in
your code.
If you specify the -anyerr option, 4GL sets the status variable after evaluating
expressions (in addition to setting it after each SQL statement executes, and
after errors in 4GL screen I/O or validation statements. The -anyerr option
overrides any WHENEVER ERROR directives in your program.
You can use the -p pathname option to specify a nondefault directory for the
object (.4go) and error (.err) les. Otherwise, any les produced by fglpc are
stored in your current working directory.
To have your compiled programcheck array bounds at runtime, specify the
-a option. The -a option requires additional processing, so you might prefer
to use this option only for debugging during development.
If you typically compile with the same options, you can set the FGLPCFLAGS
environment variable to supply those options implicitly. See the section
FGLPCFLAGS on page D-42 for details of this feature.
The -globcurs option lets you make the names of cursors and of prepared
objects global to the entire program. The compilers still require you to declare
the cursor before using it for any other purpose in the module, so this option
is seldomuseful. This option might help in debugging, however, because the
cursor names are not modied. See the section The -globcurs and -localcurs
Options on page 1-38 for more information about the scope of cursor names.
The -localcurs option can override the -globcurs option if that was set in the
C4GLFLAGS environment variable, and makes the names of cursors and
prepared objects local to the module in which they were declared.
To display the version number of the software, specify the -V option. The
version number of your SQL and p-code compiler software appears on the
screen. Any other command options are ignored. After displaying this infor-
mation, the program terminates without compiling.
1-76 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Examples
The following command compiles a 4GL source le single.4gl, and creates a
le called single.4go in the current directory:
fglpc single.4gl
The next command line compiles two 4GL source les:
fglpc -p /u/ken fileone filetwo
This command generates two compiled les, leone.4go and letwo.4go,
and stores them in subdirectory /u/ken. Any compiler error messages are
saved in le leone.err or letwo.err in the same directory.
Concatenating Multi-Module Programs
If a program has several modules, the compiled modules must all be
concatenated into a single le, as represented in Figure 1-6.
Figure 1-6
Creating and Running a
Multi-Module Program
Text
editor
. 4gl
source
le
. 4go
p-code
object
les
P-code
runner
fglgo
P-code
compiler
fglpc
Concatenation
utility
. 4gi
p-code
executable
les
Compi l i ng INFORMIX- 4GL Source Fi l es 1-77
Creati ng Programs at the Command Li ne
The UNIX cat command combines the listed les into the le specied after
the redirect ( > ) symbol. For example, the following commandcombines a list
of .4go les into a new le called new.4gi:
cat file1.4go file2.4go ... fileN.4go new.4gi
The new lename of the combined le must have either a .4go or a .4gi
extension. The extension .4gi designates runable les that have been
compiled (and concatenated, if several source modules make up the
program). You might wish to followthis convention in naming les, because
only .4gi les are displayed from within the Programmers Environment.
This convention is also a convenient way to distinguish complete program
les fromobject les that are individual modules of a multi-module program.
If your 4GL programcalls C functions or ESQL/C functions, you must follow
the procedures described in RDS Programs That Call C Functions on
page 1-79 before you can run your application.
Running RDS Programs
To execute a compiled 4GL programfromthe command line, you can invoke
the p-code runner, fglgo.
fglgo Command
The fglgo command supports the following syntax.
Element Description
lename is the name of a compiled 4GL le. The lename must have a .4go or
.4gi extension. You do not need to enter this extension.
argument are any arguments required by your 4GL program.
-anyerr
fglgo argument
-V
lename
.4go
.4gi
1-78 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
If you do not specify a lename extension, fglgo looks rst for the lename
with a .4gi extension, and then for the lename with a .4go extension.
Unlike fglpc, the fglgo command needs no -a option to check array bounds
at runtime, because array bounds are always checked by default.
If you specify the -anyerr option, 4GL sets the status variable after evaluating
expressions. This option overrides any WHENEVER ERROR statements.
To display the version number of the software, specify the -V option. The
version number of your SQL and p-code software appears on the screen. Any
other command options are ignored. After displaying this information, the
programterminates without invoking the p-code runner. 4GL runners earlier
than Version 7.3 cannot run programs that use 7.3 or later compilers, and you
must recompile programs compiled with earlier versions of the 4GL compiler
before a 7.3 or later runner can interpret them.
Important: To run a 4GL program that calls programmer-dened C functions, you
cannot use fglgo. You must instead use a customized p-code runner. RDS
Programs That Call C Functions on page 1-79 describes howto create a customized
runner.
Examples
To run a compiled program named myprog.4go, enter the following
command line at the operating system prompt:
fglgo myprog
or:
fglgo myprog.4go
Running Multi-Module Programs
To run a program with multiple modules, you must compile each module
and then combine them by using an operating system concatenation utility,
as described in an earlier section. For example, if mod1.4go, mod2.4go, and
mod3.4go are compiled 4GL modules that you wish to run as one program,
you must rst combine them as in the following example:
cat mod1.4go mod2.4go mod3.4go > mods.4gi
Compi l i ng INFORMIX- 4GL Source Fi l es 1-79
Creati ng Programs at the Command Li ne
You can then run the mods.4gi program by using the command line:
fglgo mods
or:
fglgo mods.4gi
Running Programs with the Interactive Debugger
You can also run compiled 4GL programs with the 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
runtime errors in your 4GL programs and to become more familiar with 4GL
programs. The Debugger must be purchased separately.
If you have the Debugger, you can invoke it at the system prompt with a
command line of the form:
fgldb filename
where lename is any runable 4GL le that you produced by an fglpc
command.
For the complete syntax of the fgldb command, see the Guide to the
INFORMIX-4GL Interactive Debugger.
RDS Programs That Call C Functions
If your Rapid Development System program calls programmer-dened C
functions, you must create a customized runner to execute the program.
To create a customized runner
1. Edit a structure denition le to contain information about your C
functions.
This le is named fgiusr.c and is supplied with 4GL.
2. Compile and link the fgiusr.c le with the les that contain your C
functions.
To do this, use the cfglgo command.
1-80 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
You can then use the runner produced by the cfglgo command to run the 4GL
program that calls your C functions. Both the fgiusr.c le and the cfglgo
command are described in the sections that follow.
For an example of how to call C functions from a 4GL program, see
INFORMIX-4GL by Example.
Important: To create a customized runner, you must have a C compiler installed on
your system. If the only functions that your Rapid Development System program
calls are 4GL or ESQL/C library functions, or functions written in the 4GL language,
you do not need a C compiler and you do not need to follow the procedures described
in this section.
Editing the fgiusr. c File
The d fgiusr.c le is located in the /etc subdirectory of the directory in which
you installed 4GL (that is, in $INFORMIXDIR/etc). The following listing
shows the fgiusr.c le in its unedited form:
/**********************************************************
* *
* INFORMIX SOFTWARE, INC. *
* *
* Title: fgiusr.c *
* Sccsid: @(#)fgiusr.c 4.2 8/26/87 10:48:37 *
* Description: *
* definition of user C functions *
* *
***********************************************************
*/
/*******************************************************
* This table is for user-defined C functions.
*
* Each initializer has the form:
*
* "name", name, nargs
*
* Variable # of arguments:
*
* set nargs to -(maximum # args)
*
* Be sure to declare name before the table and to leave the
* line of 0s at the end of the table.
*
Compi l i ng INFORMIX- 4GL Source Fi l es 1-81
Creati ng Programs at the Command Li ne
* Example:
*
* You want to call your C function named "mycfunc" and it expects
* 2 arguments. You must declare it:
*
* int mycfunc();
*
* and then insert an initializer for it in the table:
*
* "mycfunc", mycfunc, 2
*********************************************************
*/
#include "fgicfunc.h"
cfunc_t usrcfuncs[] =
{
0, 0, 0
};
The fgiusr.c le is a C language le that you can edit to declare any number
of programmer-dened C functions.
To edit fgiusr.c, you can copy the le to any directory. (Unless this is your
working directory at compile time, you must specify the full pathname of the
edited fgiusr.c le when you compile.) Edit fgiusr.c to specify the following:
B A declaration for each function:
int function-name( int nargs);
B Three initializers for each function:
" function-name ", function-name, [ - ] integer,
In the declaration of the function, the parenthesis symbols ( ) must follow
the function-name.
The rst initializer is the function name between double quotation marks and
is a character pointer.
The second initializer is the function name (without quotation marks) and is
a function pointer. It cannot include a parentheses.
The third initializer is an integer representing the number of arguments
expected by the function. If the number of arguments expected by the
function can vary, you must make the third argument the maximumnumber
of arguments, prexed with a minus ( - ) sign.
You must use a comma ( , ) symbol to separate each of the three initializers.
Insert a set of initializers for each C function that you declare. Aline of three
zeroes indicates the end of the structure.
1-82 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Here is an example of an edited fgiusr.c le:
#include "fgicfunc.h"
int function-name();
cfunc_t usrcfuncs[] =
{
{"function-name",function-name,1},
{ 0,0,0 }
};
Here the 4GL program will be able to call a single C function called
function-name that has one argument.
If you have several 4GL programs that call C functions, you can use fgiusr.c
in either of two ways:
B 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.
B You can create several application-specic runners.
In this case, you can either make a copy of the fgiusr.c le (with a
newname) for each customized runner, or you can re-edit fgiusr.c to
contain information on the C functions for a specic application
before you compile and link. If you create several runners, you must
know which customized runner to use with each 4GL application.
In some situations the rst method is more convenient, because users do not
need 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 ESQL/C modules that contain functions
declared in an edited fgiusr.c le. The customized runner can also run 4GL
programs that do not call C functions.
Compi l i ng INFORMIX- 4GL Source Fi l es 1-83
Creati ng Programs at the Command Li ne
cfglgo Command
The cfglgo command supports the following syntax.
You need the ESQL/C product to compile .ec les with cfglgo.
The cfglgo command compiles and links the edited fgiusr.c le with your
C program les into an executable program that can run your 4GL appli-
cation. Here fgiusr.c is the name of the le that you edited to declare C or
ESQL/C functions. If the fgiusr.c le to be linked is not in the current
directory, you must specify a full pathname. You can also rename the fgiusr.c
le.
If you do not specify the -o newfglgo option, the new runner is given the
default name a.out.
To display the version number of the software, specify the -V option. The
version number of your SQL and p-code software appears on the screen. Any
other command options are ignored. After displaying this information, the
program terminates without creating a customized p-code runner.
Element Description
cle is the name of a source le containing ESQL/C or C functions to be
compiled and linked with the newrunner, or the name of an object le
previously compiled from a .c or .ec le. You can specify any number
of uncompiled or compiled C or ESQL/C les in a cfglgo command
line.
newfglgo species the name of the customized runner.
cfglgo -o newfglgo
-V
cle
.c
.o
fgiusr.c .ec
1-84 INFORMIX- 4GL Reference Manual
Creati ng Programs at the Command Li ne
Examples
The following example 4GL program calls the C function prdate( ):
prog.4gl:
main
. . .
call prdate()
. . .
end main
The function prdate( ) is dened in le cfunc.c, as shown here:
cfunc.c:
#include <errno.h>
#include <stdio.h>
#include <time.h>
int prdate(int nargs)
{
/* This program timestamps file FileX */
long cur_date;
FILE *fptr;
time(&cur_date);
fptr = fopen("time_file","a");
fprintf(fptr,"FileX was accessed %s", ctime(&cur_date));
fclose(fptr);
return(0);
}
The C function is declared and initialized in the following fgiusr.c le:
fgiusr.c:
1 #include "fgicfunc.h"
2
3 int prdate();
4 cfunc_t usrcfuncs[] =
5 {
6 { "prdate", prdate, 0 },
7 { 0, 0, 0 }
8 };
Compi l i ng INFORMIX- 4GL Source Fi l es 1-85
Creati ng Programs at the Command Li ne
An explanation of this example of an fgiusr.c le follows.
In this example, you can use the following commands to compile the 4GL
program, to compile the new runner, and to run the program:
B To compile the example 4GL program:
fglpc prog.4gl
B To compile the new runner:
cfglgo fgiusr.c cfunc.c -o newfglgo
B To run the 4GL program:
newfglgo prog.4go
Running Programs That Call C Functions
After you create a customized runner, you can use it to execute any 4GL
programwhose Cfunctions you correctly specied in the edited fgiusr.c le.
The syntax of a customized runner (apart from its name) is the same as the
syntax of fglgo, as described in Running RDS Programs on page 1-77.
You can also create a customized Debugger to run a 4GL programthat calls C
functions. See the Guide to the INFORMIX-4GL Interactive Debugger for details
and an example of how to create a customized debugger.
Line Description
1 The le fgicfunc.h is always included. This line already exists in the
unedited fgiusr.c le.
3 This is the declaration of the function prdate( ). You must add this line
to the le.
4 This line already exists in the unedited le. It declares the structure
array usrcfuncs.
6 This line contains the initializers for function prdate( ). Because it
expects no arguments, the third value is zero.
7 The line of three zeros indicates that no more functions are to be
included.
1-86 INFORMIX- 4GL Reference Manual
Program Fi l ename Extensi ons
Important: You cannot create a customized runner or debugger from within the
Programmers Environment. You must work fromthe systemprompt and follow the
procedures described in Creating Programs at the Command Line on page 1-72 if
you are developing a 4GL programthat calls user-dened C functions. Then you can
return to the Programmers Environment and use the Program_Runner option of
the MODI FY PROGRAM menu or the NEW PROGRAM menu to specify the name
of a customized runner or debugger.
Program Filename Extensions
Source, runable, error, and backup les generated by 4GL are stored in the
current directory and are labeled with the appropriate lename extensions,
as described in the following table. These les are produced during the
normal course of using the Rapid Development System.
The last three les do not exist unless you create or modify a screen form
specication le, as described in Chapter 6.
File Description
le.4gl 4GL source le
le.4go 4GL le that has been compiled to p-code
le.4gi 4GL le that has been compiled to p-code
le.err 4GL source error le, created when an attempt to compile a module fails
or produces a warning. (The le contains the 4GL source code plus
compiler syntax warnings or error messages.)
le.erc 4GL object error le, created when an attempt to compile or link a
non-4GL source-code or object module fails (The le contains 4GL
source code and annotated compiler errors.)
le.per FORM4GL source le
le.frm FORM4GL object le
le.err FORM4GL source error le
Compi l i ng INFORMIX- 4GL Source Fi l es 1-87
Program Fi l ename Extensi ons
The following table lists backup les that are produced when you use 4GL
from the Programmers Environment.
Under normal conditions, 4GL creates the backup les and intermediate
les as necessary, and deletes them when a compilation is successful. If you
interrupt a compilation, you might nd one or more of the les in your
current directory.
If you compile with a fglpc command line that includes the p pathname
option, 4GL creates the .4gi, .4go, .err, and corresponding backup les in the
directory specied by pathname, rather than in your current directory.
During the compilation process, 4GL stores a backup copy of the le.4gl
source le in le.4bl. The time stamp is modied on the (original) le.4gl
source le, but not on the backup le.4bl le. In the event of a system crash,
you might need to replace the modied le.4gl le with the backup copy
contained in the le.4bl le.
The Programmers Environment does not allow you to begin modifying a
.4gl or .per source le if the corresponding backup le already exists in the
same directory. After an editing session terminates abnormally, for example,
you must delete or rename any backup le before you can resume editing
your 4GL module or formspecication fromthe Programmers Environment.
Warning: INFORMIX-4GL is not designed to support two or more programmers
working concurrently in the same directory. If several developers are working on the
same 4GL application, make sure that they do their work in different directories.
File Description
le.4bl 4GL source backup le, created during the modication and compi-
lation of a .4gl program module
le.4bo Object backup le, created during the compilation of a .4go program
module
le.4be Object backup le, created during the compilation of a .4gi program
module
le.pbr FORM4GL source backup le
le.fbm FORM4GL object backup le
2
Chapter
The INFORMIX-4GL Language
In This Chapter . . . . . . . . . . . . . . . . . . . . 2-3
Language Features . . . . . . . . . . . . . . . . . . . 2-3
Lettercase Insensitivity . . . . . . . . . . . . . . . . 2-3
Whitespace, Quotation Marks, Escape Symbols,
and Delimiters. . . . . . . . . . . . . . . . . . 2-4
Character Set . . . . . . . . . . . . . . . . . . . 2-5
4GL Statements. . . . . . . . . . . . . . . . . . . 2-5
Comments . . . . . . . . . . . . . . . . . . . . 2-8
Comment Indicators. . . . . . . . . . . . . . . . 2-8
Restrictions on Comments . . . . . . . . . . . . . 2-8
Conditional Comments. . . . . . . . . . . . . . . 2-9
Source-Code Modules and Program Blocks . . . . . . . . . 2-10
Statement Blocks . . . . . . . . . . . . . . . . . . 2-12
Statement Segments . . . . . . . . . . . . . . . . . 2-13
4GL Identiers . . . . . . . . . . . . . . . . . . . 2-14
Naming Rules for 4GL Identiers . . . . . . . . . . . 2-14
Naming Rules for SQL Identiers . . . . . . . . . . . 2-15
Scope of Reference of 4GL Identiers . . . . . . . . . . 2-17
Scope and Visibility of SQL Identiers . . . . . . . . . 2-19
Visibility of Identical Identiers . . . . . . . . . . . . 2-19
Interacting with Users . . . . . . . . . . . . . . . . . . 2-22
Ring Menus . . . . . . . . . . . . . . . . . . . . 2-22
Selecting Menu Options . . . . . . . . . . . . . . 2-23
Ambiguous Keyboard Selections . . . . . . . . . . . 2-24
Hidden Options and Invisible Options . . . . . . . . . 2-24
Disabled Menus . . . . . . . . . . . . . . . . . 2-24
Reserved Lines for Menus. . . . . . . . . . . . . . 2-24
2-2 INFORMIX- 4GL Reference Manual
Screen Forms. . . . . . . . . . . . . . . . . . . . 2-25
Visual Cursors . . . . . . . . . . . . . . . . . . 2-26
Field Attributes . . . . . . . . . . . . . . . . . 2-27
Reserved Lines. . . . . . . . . . . . . . . . . . 2-27
4GL Windows . . . . . . . . . . . . . . . . . . . 2-28
The Current Window . . . . . . . . . . . . . . . 2-28
On-Line Help . . . . . . . . . . . . . . . . . . . 2-29
The Help Key and the Message Compiler . . . . . . . . 2-30
The Help Window . . . . . . . . . . . . . . . . 2-30
Nested and Recursive Statements . . . . . . . . . . . . 2-31
Early Exits from Nested and Recursive Operations . . . . . 2-35
Exception Handling. . . . . . . . . . . . . . . . . . . 2-39
Compile-Time Errors and Warnings . . . . . . . . . . . . 2-39
Runtime Errors and Warnings . . . . . . . . . . . . . . 2-39
Normal and AnyError Scope . . . . . . . . . . . . . 2-40
A Taxonomy of Runtime Errors . . . . . . . . . . . . 2-41
Default Error Behavior and ANSI Compliance . . . . . . . 2-42
Changes to 4GL Error Handling . . . . . . . . . . . . . 2-43
Error Handling with SQLCA . . . . . . . . . . . . . . 2-44
The INFORMIX- 4GL Language 2-3
In This Chapter
An INFORMIX-4GL program consists of at least one source le that contains
a series of English-like statements. These obey a well-dened syntax that this
book describes.
This chapter presents a brief overviewof the 4GL language. Its theory, appli-
cation, constructs, and semantics are described in detail in INFORMIX-4GL
Concepts and Use, a companion volume to this manual.
This manual assumes that you are using Informix Dynamic Server as your
database server. Features specic to INFORMIX-SE are noted.
Language Features
4GL is an English-like C or COBOL-replacement programming language that
Informix Software, Inc., introduced in 1986 as a tool for creating relational
database applications. Its statement set (see Chapter 4, INFORMIX-4GL
Statements) includes the industry-standard SQL language for accessing and
manipulating a relational database. The 4GL development environment
provides a complete environment for writing 4GL programs.
Lettercase Insensitivity
4GL is case insensitive, making no distinction between uppercase and
lowercase letters, except within quoted strings. Use pairs of double ( " ) or
single ( ' ) quotation marks in 4GL code to preserve the lettercase of character
literals, lenames, and names of database entities, such as cursor names.
You can mix uppercase and lowercase letters in the identiers that you assign
to 4GL entities, but any uppercase letters in 4GL identiers are automatically
shifted to lowercase during compilation.
2-4 INFORMIX- 4GL Reference Manual
Whi tespace, Quotati on Marks, Escape Symbol s, and Del i mi ters
Whitespace, Quotation Marks, Escape Symbols,
and Delimiters
4GL is free-form, like C or Pascal, and generally ignores TAB characters,
LINEFEED characters, comments, and extra blank spaces between statements
or statement elements. You can freely use these whitespace characters to
make your 4GL source code easier to read.
Blank (ASCII 32) characters act as delimiters in some contexts. Blank spaces
must separate successive keywords or identiers, but cannot appear within
a keyword or identier. Pairs of double ( " ) or single ( ' ) quotation marks
must delimit any character string that contains a blank (ASCII 32) or other
whitespace character, such as LINEFEED or RETURN.
Do not mix double and single quotation marks as delimiters of the same
string. For example, the following is not a valid character string:
'Not A valid character string"
If you are using Informix DRDA software to access a non-Informix relational
database, such as a DB2 database fromIBM, double quotation marks might
not be recognized as delimiters by the non-Informix database.
Similarly, most 4GL statements require single quotation marks if the database
supports delimited SQL identiers, and in this special case cannot use double
quotation marks in most contexts, because when the DELIMIDENT
environment variable is set, double quotation marks are reserved for SQL
identiers.
To include literal quotation marks within a quoted string, precede each literal
quotation mark with the backslash (\), or else enclose the string between a
pair of the opposite type of quotation marks:
DISPLAY "Type 'Y' if you want to reformat your disk."
DISPLAY 'Type "Y" if you want to reformat your disk.'
DISPLAY 'Type \'Y\' if you want to reformat your disk.'
The 4GL compiler treats a backslash as the default escape symbol, and treats
the immediately following symbol as a literal, rather than as having special
signicance. To specify anything that includes a literal backslash, enter
double ( \\ ) backslashes wherever a single backslash is required. Similarly,
use \\\\ to represent a literal double backslash.
The INFORMIX- 4GL Language 2-5
Character Set
Except in some PREPARE and PRINT statements, and the END SQL keywords
in SQL blocks, 4GL requires no statement terminators, but you can use the
semicolon (; ) as a statement terminator.
Statements of the SQL language, however, that include syntax later than what
Informix 4.10 database servers support require SQLEND SQL delimiters,
unless the post-4.10 SQL statement appears as text in a PREPARE statement.
Character Set
4GL requires the ASCII character set, but also supports characters from the
client locale in data values, identiers, form specications, and reports. For
more information, see Naming Rules for 4GL Identiers on page 2-14.
4GL Statements
4GL source-code modules can contain statements and comments:
B A statement is a logical unit of code within 4GL programs. See
Chapter 4 for a list of the statements in the 4GL statement set.
B A comment is a specication that 4GL disregards. For more infor-
mation, see Comment Indicators on page 2-8.
A compilation error occurs if a program (or one of its modules or statement
blocks) includes part of a statement but not all of the required elements.
Statements of 4GL can contain identiers, keywords, literal values, constants,
operators, parentheses, and expressions. These terms are described in subse-
quent sections of this chapter, and in Chapter 4.
For the purposes of this manual, 4GL supports two types of statements:
B SQL (Structured Query Language) statements
B Other 4GL language statements
This distinction among statements reects whether they provide instructions
to the database server (SQL statements) or instructions to the client appli-
cation (other 4GL statements). INFORMIX-4GL Concepts and Use describes the
process architecture of 4GL applications. See the documentation of your
Informix database server for the syntax of SQL statements. Chapter 4 of this
manual describes the syntax of 4GL statements that are not SQL statements.
2-6 INFORMIX- 4GL Reference Manual
4GL Statements
Where a given statement can appear within a 4GL program, how the Inter-
active Debugger treats it, and whether the statement has its effect at compile
time or at runtime all depend on whether the statement is executable.
The following statements of 4GL are non-executable. They dene program
blocks, declare 4GL identiers, or act as compiler directives.
The following statements of 4GL are executable.
4GL statements (individually described in Chapter 4) begin with keywords.
Some statements can include delimiters (as described earlier in this section)
and expressions (as described in Chapter 3, Data Types and Expressions).
DEFER FUNCTION LABEL REPORT
DEFINE GLOBALS MAIN WHENEVER
CALL FOREACH OPTIONS
CASE FREE OUTPUT TO REPORT
CLEAR GOTO PAUSE
CLOSE FORM IF PRINT
CLOSE WINDOW INITIALIZE PROMPT
CONSTRUCT INPUT RETURN
CONTINUE INPUT ARRAY RUN
CURRENT WINDOW LET SCROLL
DISPLAY LOAD SKIP
DISPLAY ARRAY LOCATE SLEEP
DISPLAY FORM MENU START REPORT
ERROR MESSAGE TERMINATE REPORT
EXIT NEED UNLOAD
FINISH REPORT OPEN FORM VALIDATE
FOR OPEN WINDOW WHILE
The INFORMIX- 4GL Language 2-7
4GL Statements
Within the broad division into SQL statements and other statements, the 4GL
statement set can be further classied into functional categories, whose
component statements are listed in The 4GL Statement Set on page 4-9.
The 4GL Statement Set on page 4-9 identies the SQL statements and other
4GL statements that make up these functional categories.
Some statements, called compound statements (described in Statement
Blocks on page 2-12), can contain other 4GL statements. Aset of nested state-
ments within a compound statement is called a statement block. When
necessary, 4GL uses END (with another keyword to indicate a specic
statement) to terminate a compound statement.
Except in a few special cases, like multiple-statement prepared entities, 4GL
requires no statement terminators, but you can use the semicolon as a
statement terminator. If you have difculty interpreting a compilation error,
you might want to insert semicolons to separate the statements that precede
the error message, to indicate to the 4GL compiler where each statement ends.
(The PRINT statement in 4GL reports can use semicolons to control the format
of output from a report by suppressing LINEFEED.)
Screen forms of 4GL are manipulated by formdrivers but are dened in form
specication les. These ASCII les use a syntax that is distinct from the
syntax of other 4GL features. See Chapter 6, Screen Forms, for details of the
syntax of 4GL form specication les.
Types of SQL Statements Other Types of 4GL Statements
Data denition statements
Data manipulation statements
Cursor manipulation statements
Dynamic management statements
Query optimization statements
Data access statements
Data integrity statements
Stored procedure statements
Optical statements
Denition and declaration statements
Program ow control statements
Compiler directives
Storage manipulation statements
Screen interaction statements
Report execution statements
2-8 INFORMIX- 4GL Reference Manual
Comments
Comments
Acomment is text in 4GL source code to assist human readers, but which 4GL
ignores. (This meaning of comment is unrelated to the COMMENTS attribute
in a form, or to the OPTIONSCOMMENT LINE statement, both of which
control on-screen text displays to assist users of the 4GL application.)
Comment Indicators
You can indicate comments in any of several ways:
B Acomment can begin with the left-brace ( { ) and end with the right-
brace ( } ) symbol. These can be on the same line or on different lines.
B The pound ( # ) symbol (sometimes called the sharp symbol) can
begin a comment that terminates at the end of the same line.
B You can use a pair of hyphens or minus signs ( -- ) to begin a
comment that terminates at the end of the current line. (This
comment indicator conforms to the ANSI standard for SQL.)
4GL ignores all text between braces (or fromthe # or -- comment indicator
to the end of the same line).
For clarity andto simplify programmaintenance, it is recommendedthat you
document your 4GL code by including comments in your source les. You
can also use comment indicators during program development to disable
statements without deleting them from your source-code modules.
Restrictions on Comments
When using comments, keep the following restrictions in mind:
B Within a quoted string, 4GL interprets comment indicators as literal
characters, rather than as comment indicators.
B Comments cannot appear in the SCREEN section of a form speci-
cation le.
B The # symbol cannot indicate comments in a formspecication, in an
SQL statement block, nor in the text of a prepared statement.
B You cannot use braces ( { } ) to nest comments within comments.
The INFORMIX- 4GL Language 2-9
Comments
B You cannot specify consecutive minus signs ( -- ) in arithmetic
expressions, because 4GL interprets what follows as a comment.
Instead, use a blank space or parentheses to separate consecutive
arithmetic minus signs. For example:
LET x = y --3 # Now variable x evaluates as y
# because 4GL ignores text after --
LET x = y -(-3) # Now variable x evaluates as (y + 3).
B The symbol that immediately follows the -- comment indicator
must not be the sharp (#) or at (@) symbols, unless you intend to
compile the same 4GL source le with the Dynamic 4GL product. See
the next section, Conditional Comments on page 2-9, for details of
the special signicance of the # or @ symbol after the -- symbols.
Conditional Comments
Another Informix product, Informix Dynamic 4GL, treats the --# characters
as a whitespace character, rather than as the beginning of a comment. This
feature provides backward compatibility for source-code modules that begin
lines containing Dynamic 4GL extensions to 4GL syntax with those symbols.
When compiled by Dynamic 4GL, lines so marked are treated as statements
in a graphical user interface (GUI) environment. 4GL, however, interprets --
# as a comment symbol so that Dynamic 4GL syntax extensions (or anything
else) that follow in the same line are ignored.
Conversely, the --@ symbols act as a conditional comment indicator. The 4GL
compiler interprets this indicator as a single whitespace character and reads
the rest of the line. In contrast, the Dynamic 4GL compiler interprets this as a
comment and ignores the rest of the line.
These symbols are called conditional comment indicators because their
interpretation depends on which compiler you use. Together, these features
enable the same source le to support different features, depending on
whether you compile with Dynamic 4GL or with 4GL.
Conditional comments are supported both in source (.4gl) les, in formspeci-
cation (.per) les, and in INFORMIX-SQL report (.ace) les.
For example, you could use conditional comments to specify a Help le:
--# OPTIONS HELP FILE "d4gl_help.42h" --Line is ignored by I-4GL
--@ OPTIONS HELP FILE "i4gl_help.iem" --Line is ignored by D-4GL
2-10 INFORMIX- 4GL Reference Manual
Source- Code Modul es and Program Bl ocks
The following example shows a fragment of a form specication:
ATTRIBUTES
f0 = FORMONLY.name, --#char_var ;
--@REVERSE ;
Conditional comments are also valid within SQL statement blocks, but not
within the text of a PREPARE statement.
Do not put both forms of conditional comments in the same line.
Source-Code Modules and Program Blocks
When you create a 4GL program, enter statements and comments into one or
more source code les, called modules, whose lenames can have no more
than 10 characters, excluding any le extensions.
Because 4GL is a structured language, executable statements are organized
into larger units, called program blocks (sometimes called routines, sections, or
functions). 4GL modules can include three different kinds of programblocks:
MAIN, FUNCTION, and REPORT.
Each block begins with the keyword after which it is named, and ends with
the corresponding END statement keywords (ENDMAIN, ENDFUNCTION, or
ENDREPORT). Programblocks can support 4GL applications in several ways:
B As part of a complete 4GL program(one that includes a MAIN block)
B As a FUNCTION or REPORT block that is invoked by a 4GL program
B As a 4GL FUNCTION block called by a C or ESQL/C program
(INFORMIX-ESQL/C requires a separate license.)
FUNCTION Statement
p. 4-143
REPORT Statement
p. 4-334
MAIN Statement
p. 4-247
The INFORMIX- 4GL Language 2-11
Source- Code Modul es and Program Bl ocks
The following rules apply to 4GL program blocks:
B Every 4GL programmust contain exactly one MAINblock. This must
be the rst program block of the module in which it appears.
B Except for certain declarations (DATABASE, DEFINE, GLOBALS),
no 4GL statement can appear outside a program block.
B Variables that you declare within a program block have a scope of
reference (described in Scope of Reference of 4GL Identiers on
page 2-17) that is local to the same program block. They cannot be
referenced from other program blocks. (Variables that you declare
outside any programblock have a scope of reference extending from
their declaration until the end of the same source module.)
B The GO TO or GOTO keywords cannot reference a statement label in
a different program block. (For more information about statement
labels, see the GOTO and LABEL statements in Chapter 4.)
B Programblocks cannot be nested; neither can any programblock be
divided among more than one source-code module.
B The DATABASE statement (described in Chapter 4) has a compile-
time effect when it appears before the rst programblock of a source
module. Within a program block, it has a runtime effect.
B The scope of the WHENEVER statement extends from its occurrence
to the next WHENEVER statement that species the same exceptional
condition, or to the end of the same module (whichever comes rst),
but WHENEVER cannot occur outside a program block.
CALL, RETURN, EXIT REPORT, START REPORT, OUTPUT TO REPORT, FINISH
REPORT, and TERMINATE REPORT statements, and any 4GL expression that
includes a programmer-dened function as an operand, can transfer control
of program execution between program blocks. These statements are all
described in Chapter 4; expressions of 4GL are described in Chapter 3.
Chapter 5, Built-In Functions and Operators, describes FUNCTION blocks,
and Chapter 7 describes REPORT blocks. (See Chapter 1 for details of how
source-code modules are compiled and linked to create applications, and for
details about the naming conventions for lenames and for le extensions of
4GL modules.)
2-12 INFORMIX- 4GL Reference Manual
Statement Bl ocks
Statement Blocks
The MAIN, FUNCTION, and REPORT statements are special cases of compound
statements, the 4GL statements that can contain other statements.
Every compound statement of 4GL supports the END keyword to mark the
end of the compound statement construct within the source-code module.
Most compound statements also support the EXIT statement keywords, to
transfer control of execution to the statement that follows the END statement
keywords, where statement is the name of the compound statement.
By denition, every compound statement can contain at least one statement
block, a group of one or more consecutive SQL statements or other 4GL state-
ments. In the syntax diagram of a compound statement, a statement block
always includes this element.
(Some contexts permit or require semicolon ( ; ) delimiters. Any SQL
statement that is not prepared but includes syntax later than what Informix
4.10 database servers support must be enclosed between SQL and END SQL
keywords.)
These are examples of statement blocks within compound 4GL statements:
B The WHEN, OTHERWISE, THEN, or ELSE blocks of CASE and IF
statements
B Statements within FOR, FOREACH, or WHILE loops
B CONSTRUCT, DISPLAY ARRAY, INPUT, or INPUT ARRAY control
blocks
B Statements following the COMMAND clauses of MENU statements
B Statements within the ON KEY blocks of PROMPT statements
B FORMAT section control blocks of REPORT statements
B All the statements in MAIN, FUNCTION, or REPORT program blocks
CASE FOREACH INPUT PROMPT
CONSTRUCT FUNCTION INPUT ARRAY REPORT
DISPLAY ARRAY GLOBALS MAIN SQL
FOR IF MENU WHILE
statement
The INFORMIX- 4GL Language 2-13
Statement Segments
4GL permits any statement block to be empty, even if it appears as a required
element in its syntax diagram. This feature enables you to compile and
execute applications that contain empty (or dummy) functions or reports, to
test the behavior of a not-yet-complete program.
Unlike program blocks, which cannot be nested, 4GL statement blocks can
contain other statement blocks. This recursion can be static, as when a
function includes a FOREACH loop that contains an IF statement. Blocks can
also be recursive in a dynamic sense, as when a CALL statement invokes a
function only if some specied condition occurs.
Although most 4GL statements can appear within statement blocks, andmost
compound statements can be nested, some restrictions apply. In some cases,
you can circumvent these restrictions by invoking a function to execute a
statement that cannot appear directly within a given compound statement.
The GLOBALS lename statement can incorporate statement blocks indirectly
by referencing a le. The statements in the specied le are incorporated into
the current module during compilation.
Statement Segments
Any subset of a 4GL statement, including the entire statement, is called a
statement segment. For simplicity, many syntax diagrams in this book use
rectangles to represent statement segments (for example, MAIN, FUNCTION,
and REPORT in Source-Code Modules and Program Blocks on page 2-10).
These are expanded into syntax diagrams on the page referenced in the
rectangle, or elsewhere on the same page, if the rectangle indicates no page
number. For your convenience, the diagrams of a fewimportant segments are
repeated on different pages.
Chapter 4 describes certain statement segments that can appear as elements
of various 4GL statements.
2-14 INFORMIX- 4GL Reference Manual
4GL Identi ers
4GL Identiers
Statements and formspecications can reference some 4GL programentities
by name. To create a named programentity, you must declare a 4GL identier.
When you create any of the following programentities, you must followthe
guidelines in Naming Rules for 4GL Identiers on page 2-14 and adhere to
the declaration procedures of 4GL to declare a valid identier.
This list excludes columns, constraints, cursors, databases, indexes, prepared
statements, stored procedures, synonyms, tables, triggers, views, and other
database objects, because those are SQL entities, not 4GL entities. It also omits
lenames, pathnames, and user names, which must conform to the naming
rules of your operating system or network.
Naming Rules for 4GL Identiers
A4GL identier is a character string that is declared as the name of a program
entity. In the default (U.S. English) locale, every 4GL identier must conform
to the following rules:
B It must include at least one character, but no more than 50.
B Only ASCII letters, digits, and underscore ( _ ) symbols are valid.
Blanks, hyphens, and other non-alphanumerics are not allowed.
B The initial character must be a letter or an underscore.
B 4GL identiers are not case sensitive, so my_Var and MY_vaR both
denote the same identier.
Named Program Entity How Name Is Declared
4GL function or its argument FUNCTION statement
4GL program variable DEFINE and GLOBAL statements
4GL report or its argument REPORT statement
4GL screen array ATTRIBUTES section of form specication
4GL screen form OPEN FORM statement
4GL screen record INSTRUCTIONS section of form specication
4GL statement label LABEL statement
4GL table alias TABLES section of form specication
4GL window OPEN WINDOW statement
The INFORMIX- 4GL Language 2-15
4GL Identi ers
Within non-English locales, however, 4GL identiers can include non-ASCII
characters in identiers, if those characters are dened in the code set of the
locale that CLIENT_LOCALE species. In multibyte East Asian locales that
support languages whose written form is not alphabet-based, such as
Chinese, Japanese, or Korean, a 4GL identier neednot begin with a letter, but
the storage length of a 4GL identier cannot exceed 50 bytes.
Important: You might get unexpected results if you declare as an identier certain
keywords of SQL, the C and C++ languages, or your operating system or network.
(Appendix G, Reserved Words, lists some keywords and predened identiers of
4GL that should not be declared as identiers of programmer-dened entities.) If you
receive an error message that seems unrelated to the SQL or other 4GL statement that
elicits the error, see if the statement references a reserved word as an identier.
In releases of 4GL earlier than 7.3, the total length of all names of functions,
reports, and variables in an 4GL programthat was compiled to p-code could
not exceed 65,535 bytes. This release is not subject to that restriction; the
upper limit on what is called your global string space is now two gigabytes
(unless some smaller limit is imposed by the memory capacity of the system
on which the 4GL program is running).
If you are using the C Compiler version of 4GL, there is a chance that only the
rst 31 characters of a 4GL identier are recognizedby your Ccompiler. If this
is the case, or if you want your application to be portable to all C compilers,
keep the rst 31 characters unique among similar programentities that have
the same scope of reference. (Scope of reference is explained later in this
section.)
Naming Rules for SQL Identiers
The rules for SQL identiers resemble those of 4GL, with these exceptions:
B For most Informix database servers, SQL identiers are limited to no
more than 18 characters. (But database names might be limited to 8,
10, or 14 characters, depending on the database server and operating
system environment.)
B Informix 9.2 and later databases can have a limit of 128-bytes.
B SQL identiers within quoted strings are case-sensitive.
B You can use reserved words as SQL identiers (but such usage might
require qualiers, and can make your code difcult to maintain).
GLS
2-16 INFORMIX- 4GL Reference Manual
4GL Identi ers
4GL identiers can be the same as SQL identiers, but this might require
special attention within the scope of the 4GL identier. For more information,
see Scope and Visibility of SQL Identiers on page 2-19.
If the database andits connectivity software accept non-ASCII characters, 4GL
can recognize characters valid for the locale in these SQL identiers.
For INFORMIX-SE database servers, whether non-English characters are
permitted in the names of databases, tables, or log les depends on whether
the operating system permits such characters in lenames. What characters
are valid in SQL identiers depends on the database locale. See the Informix
Guide to GLS Functionality for additional details of SQL identiers.
When the client locale and the database locale are different, 4GL does not
support use of the LIKE keyword in declarations of 4GL records that assign
default names to record members, if LIKE references a table or column whose
name includes any characters outside the code set of the client locale.
Similarly, do not attempt to use the LIKE keyword with SQL identiers that
require more than 51 bytes of storage. Some Informix database servers can
support up to 128-byte identiers.
Warning: Informix database servers (Version 7.0 and later) support DELI MI DENT,
an environment variable that can extend the character set of SQL. 4GL cannot,
however, reference database entities whose names include any non-alphanumeric
characters (such as blank spaces) outside the character set of 4GL identiers.
The ANSI standard for SQL requires that all identiers, including user names,
be in uppercase letters. Before passing to the database server a user name that
includes any lowercase letters, 4GL converts the name to uppercase letters, if
the compile-time database is ANSI/ISO-compliant, or if the DBANSIWARN
variable is set, or if the -ansi compilation ag is used.
Column name Index name Synonym
Connection name Log le name Table name
Constraint name Role name Trigger name
Database name Stored procedure name View name
GLS
ANSI
The INFORMIX- 4GL Language 2-17
4GL Identi ers
To specify a user name that is all lowercase or a combination of uppercase
and lowercase letters, you must enclose the name in quotation marks. 4GL
passes to the database server any user name enclosed in quotation marks
with the case of the letters intact. When a user species this name, quotation
marks must be placed around the name. The only situations in which 4GL
does not convert an unquoted, lowercase user name to uppercase is when the
user name is informix or public.
The following example species the name james as the owner of the table
custnotes:
CREATE TABLE "james".custnotes
(customer_num INTEGER, notes CHAR(240))
You can access the table as shown in the following example:
SELECT * FROM "james".custnotes.
Scope of Reference of 4GL Identiers
Any 4GL identier can be characterized by its scope of reference, sometimes
called its name scope, or simply its scope. A point in the program where an
entity can be referenced by its identier is said to be in the scope of reference
of that identier. Conversely, any point in the program where the identier
cannot be recognized is said to be outside its scope of reference.
Identiers of Variables
The scope of reference of a variable is determined by where in the .4gl source
module the DEFINE statement appears that declares the identier. Identiers
of variables can be local, module, or (in some cases) global in their scope:
B Local 4GL variables are declared within a program block. These
variables cannot be referenced by statements outside the same
program block.
B Module variables (sometimes called modular or static) must be
declared outside any MAIN, REPORT, or FUNCTION program block.
These identiers cannot be referenced outside the same .4gl module.
If the GLOBALSENDGLOBALS statement declares variables in one module,
you can extendthe scope of those variables to any other module that includes
a GLOBALS lename statement, where lename species the le that contains
the GLOBALSEND GLOBALS statement.
2-18 INFORMIX- 4GL Reference Manual
4GL Identi ers
Module identiers whose scope has been extended to additional modules by
this mechanismare sometimes said to have global scope, even if they are out
of scope in some modules. Truly global in scope, however, are the names
of the constants NOTFOUND, TRUE and FALSE, and built-in variables like
status, int_ag, quit_ag, and the SQLCA record. These predened identi-
ers do not need to be declared. Unless you declare a conicting identier,
they are visible in any 4GL statement, and can be referenced from any 4GL
module, as can the names of the built-in functions and operators like
LENGTH( ) and INFIELD( ) that Chapter 4 describes.
Other 4GL Identiers
Also global in scope are names of 4GL windows, forms, reports, and
functions. The scope of the identiers of form entities (like screen elds,
screen arrays, screen records, or table aliases) includes all the 4GL statements
that are executed while the form is open.
The following table summarizes the scope of reference of 4GL identiers for
various types of 4GL program entities.
Named 4GL Program Entity Scope of Reference of 4GL Identier
Constant Global (for TRUE, FALSE, and NOTFOUND)
Formal argument Local to its function or report denition
Function or report Global
Variable Module (if declared outside a program block) or
local (if declared inside a program block)
Screen eld, array, or record While the form that declares it is displayed
Screen form or window Global (after it has been declared)
Statement label Local (to the program block in which it appears)
Table alias While the form that declares it is displayed
The INFORMIX- 4GL Language 2-19
4GL Identi ers
Here each line represents a separate name space. With each name space, 4GL
identiers that have the same scope of reference must be unique. (In addition
to these restrictions, a formal argument cannot have the same identier as its
own function or report.) See Visibility of Identical Identiers on page 2-19
for details of how4GL resolves conicts between non-unique identiers
within the same name space.
In C, global variables and functions share the same name space. Unless you
compile your 4GL source code to p-code, a compilation error results if a
global variable has the same identier as a 4GL function or report.
Scope and Visibility of SQL Identiers
By default, the scope of a cursor or prepared object name is fromits DECLARE
or PREPARE declaration until the module ends, or until a FREE statement
species its name. (The -globcurs compiler ag makes their scope global.)
After FREE, subsequent DECLARE or PREPARE statements in the same
module cannot reassign the same name, even to an entity that is identical to
whatever FREE referenced. All other SQL identiers have global scope.
Statements cannot reference the name of a global database entity like a table,
column, or index after an SQL data denition statement to DROP the entity is
executed, or if the database that contains the entity is not open.
If you assign to a 4GL entity the name of an SQL entity, the 4GL name takes
precedence within its scope. To avoid ambiguity in DELETE, INSERT, SELECT,
and UPDATE statements (and only in these statements), prex an @ symbol
to the name of any table or column that has the same name as a 4GL variable.
Otherwise, only the 4GL identier is visible in these ambiguous contexts.
Visibility of Identical Identiers
A compile-time error occurs if you declare the same name for two variables
that have the same scope. You can, however, declare the same name for
variables that differ in their scope. For example, you can use the same
identier to reference different local variables in different program blocks.
You can also declare the same name for two or more variables whose scopes
of reference are different but overlapping. Within their intersection, 4GL
interprets the identier as referencing the variable whose scope is smaller,
and therefore the variable whose scope is a superset of the other is not visible.
2-20 INFORMIX- 4GL Reference Manual
4GL Identi ers
Non-Unique Global and Local Variables
If a local variable has the same identier as a global variable, then the local
variable takes precedence inside the program block in which it is declared.
Elsewhere in the program, the identier references the global variable, as
illustrated in the 4GL program in Figure 2-1.
The shaded area indicates where the global identier called var is visible.
This is superseded in the MAIN statement and in the rst FUNCTION
program block by local variables that have the same name. Only the last
DISPLAY statement references the global variable; the rst two display local
variables.
Non-Unique Global and Module Variables
A module variable can have the same name as a global variable that is
declared in a different module. Within the module where it is declared, the
module variable takes precedence over the global variable. Statements in that
module cannot reference the global variable.
Figure 2-1
Precedence of Local Variables over Global Variables
GLOBALS
DEFINE var INT
MAIN
DEFINE var INT
FUNCTION first3()
DEFINE var INT
END MAIN
END FUNCTION
END GLOBALS
LET var = 3
DISPLAY var AT 2,2
DISPLAY var AT 3,3
LET var = 2
DISPLAY var AT 4,4
END FUNCTION
CALL first3()
SLEEP 2
CALL final4()
FUNCTION final4()
LET var = 4
SLEEP 2
SLEEP 2
Scope i s gl obal (enti re program).
Scope i s l ocal to the MAIN program bl ock.
Scope i s l ocal to the rst3 FUNCTION.
Scope i s gl obal (enti re program).
The INFORMIX- 4GL Language 2-21
4GL Identi ers
A module variable cannot have the same name as a global variable that is
declared in the same module.
Non-Unique Module and Local Variables
If a local variable has the same identier as a module variable, then the local
identier takes precedence inside the programblock in which it is declared.
Elsewhere in the same source-code module, the name references the module
variable, as illustrated in Figure 2-2.
The shaded area indicates where the module variable called var is visible.
This is superseded in the MAIN block and in the rst FUNCTION program
block by the identiers of local variables called var. The rst two DISPLAY
statements show values of local variables; the last displays the module
variable.
In the portion of a program where more than one variable has the same
identier, 4GL gives precedence to a module identier over a global one, and
to a local identier over one with any other scope. Assign unique names to
variables if you wish to avoid masking part of the scope of non-unique
module identiers.
Figure 2-2
Precedence of Local Variables over Module Variables
MAIN
DEFINE var INT
FUNCTION first3()
DEFINE var INT
END MAIN
END FUNCTION
DEFINE var INT
LET var = 3
DISPLAY var AT 2,2
DISPLAY var AT 3,3
LET var = 2
DISPLAY var AT 4,4
END FUNCTION
CALL first3()
SLEEP 2
CALL final4()
FUNCTION final4()
LET var = 4
SLEEP 2
SLEEP 2
Scope i s l ocal to the MAIN program bl ock.
Scope i s the enti re modul e.
Scope i s l ocal to the rst3 FUNCTION.
Scope i s the enti re modul e.
2-22 INFORMIX- 4GL Reference Manual
Interacti ng wi th Users
Interacting with Users
You can use 4GL to create applications composed of the following interface
elements:
B Menus
B Screen forms
B 4GL windows
B Help messages
B Reports based on data retrieved froman SQL database (described in
Chapter 7, INFORMIX-4GL Reports)
Ring Menus
You can use the MENU statement of 4GL to create and display a ring menu of
command options, so that users can perform the tasks that you specify. The
menu of a typical 4GL program, for example, might look like Figure 2-3.
Figure 2-3
The Format of a Typical 4GL Ring Menu
Menu ti tl e
Current opti on El l i psi s poi nts
show addi ti onal
opti ons exi st
Menu opti ons Message descri bi ng the
currentl y hi ghl i ghted menu
opti on
Options: Customer Order Customer Calls Clients State ...
Display information about current customers.
The INFORMIX- 4GL Language 2-23
Ri ng Menus
Option names are not 4GL identiers, and can include embedded blank
characters and other printable characters. By default, an option is chosen
when the user types its initial character, but you can specify additional
activation keys. Different menus can have the same option names.
If a menu has more options than can t on one line, ellipsis points automati-
cally indicate that more options appear on another page of the menu. In this
example, the ellipsis indicates that additional menu options are on one or
more pages to the right. Similarly, an ellipsis on the left means that additional
menu options are on one or more menu pages to the left.
The user can scroll to the right to display the next page of options by using
the RIGHT ARROW or SPACEBAR, or scroll to the left with the LEFT ARROW.
You can nest MENU statements within other MENU statements, so that the
menus form a hierarchy. A nested MENU statement can appear directly
within a menu control block, or else in a function that is called directly or
indirectly when the user chooses an option of the enclosing menu.
Selecting Menu Options
By pressing RETURN, the user can select the menu option that is currently
highlighted in reverse video. In the previous example, Customer would be
selected. The highlight that indicates the current option is called the menu
cursor.
The menu in Figure 2-3 on page 2-22 is called a ring menu because the menu
cursor behaves as if the list of options were cyclic: if the user moves the cursor
to the right, past the last option, then the rst option is highlighted. Similarly,
moving the menu cursor to the left, past the rst option, highlights the last
option.
Pressing the key that matches the initial character of a menu option, such as
O (for Order) in the preceding illustration, selects the corresponding option.
All other options are disabled until the associated COMMAND block
completes its execution. Disabled menu options cannot be selected.
2-24 INFORMIX- 4GL Reference Manual
Ri ng Menus
Ambiguous Keyboard Selections
If the user makes an ambiguous menu option selection (for example, by
typing C in the 4GL menu containing Customer, Customer Calls, and Clients
in the previous example, 4GL clears the second line of the menu and prompts
the user to clarify the choice. 4GL displays each keystroke, followed by the
names of the menu options that begin with the typed letters. When 4GL
identies a unique option, it closes this prompt line and executes the state-
ments associated with the selected menu option. Pressing BACKSPACE undoes
the most recently typed key.
Hidden Options and Invisible Options
You can suppress the display of any subset of the menu options, disabling
these hidden options. The HIDE OPTION and SHOW OPTION Keywords
on page 4-263 describes how the MENU statement can programmatically
control whether a menu option is hidden or accessible.
Menus can also include invisible options. An invisible option does not appear
in the menu, but it performs the specied actions when the user presses the
activation key. For a description of how to create invisible options, see
Invisible Menu Options on page 4-259.
Disabled Menus
Menus themselves are not always accessible. During screen interaction state-
ments like INPUT, CONSTRUCT, INPUT ARRAY, and DISPLAY ARRAY, errors
would be likely to result if the user could interrupt the interaction with menu
choices. 4GL prevents these errors by disabling the entire menu during the
execution of these statements. The menu does not change its appearance
when it is disabled.
Reserved Lines for Menus
The rst line (called the Menu line) lists a title and options of the menu. A
menu cursor (a double border) highlights the current option. For each option,
a menu control block species statements to execute if the user chooses the
option. (For more information, see The MENU Control Blocks on
page 4-252).
The INFORMIX- 4GL Language 2-25
Screen Forms
The next line (called the Menu Help line) displays a prompt for the currently
highlighted option. If the user moves the menu cursor to another option, this
prompt is replaced by one for the new current option.
Screen Forms
A screen form is a 4GL display in which the user can view, enter, or edit data.
Chapter 6, Screen Forms, describes how to create screen forms.
The following visual elements (described in greater detail in Chapter 6) can
appear in a 4GL screen form:
B Fields. Also called formelds or screen elds, these areas are where
the user enters or edits data, or the 4GL program displays a value.
B Field delimiters. Fields are usually enclosed within brackets.
B Screen records. These are logically related sets of elds.
B Screen arrays. These are scrollable arrays of elds or records.
B Decorative rectangles. These can ornament the form.
B Text. Anything else in the form is called text. Text always appears
while the form is visible.
2-26 INFORMIX- 4GL Reference Manual
Screen Forms
Text can include labels and titles, as in Figure 2-4.
Visual Cursors
4GL marks the users current location (if any) in the current menu, form, or
eld with a visual cursor. Usually, each of these is simply called the cursor:
B Menu cursor. Reverse video marks the option chosen if you press
RETURN.
B Field cursor. This pipe symbol ( | ) marks the current character
position in the current eld.
Figure 2-4
Visual Elements on a Screen Form
Form ti tl e
Text
Decorati ve l i ne
Screen el d
ORDER FORM
-----------------------------------------------------------------------------
-
Customer Number: [ ]
First Name: [ ] Last Name: [Grant|Miller ]
Address: [ ]
[ ]
City: [ ] State: [ ] Zip: [ ]
Telephone: [ ]
-----------------------------------------------------------------------------
-
Order No: [ ] Order Date: [>06/05/89 ] Ship Date: [ ]
Item No. Stock No. Code Description Quantity Price Total
[ ] [ ] [ ] [ ] [ ] [ ] [ ]
[ ] [ ] [ ] [ ] [ ] [ ] [ ]
[ ] [ ] [ ] [ ] [ ] [ ] [ ]
[ ] [ ] [ ] [ ] [ ] [ ] [ ]
-----------------------------------------------------------------------------
The INFORMIX- 4GL Language 2-27
Screen Forms
Field Attributes
Several 4GL statements can set display attributes (as described in
ATTRIBUTE Clause on page 3-97). A form specication le can also
specify eld attributes. These optional descriptors can control the display
when the cursor is in the eld, or can supply or restrict eld values during
data entry. Field attributes can have effects like these:
B They control cursor movement among elds.
B They set validation and default value eld attributes.
B They set formatting attributes or automatically invoke a multiple-
line editor for character data, or an external editor to viewor modify
TEXT or BYTE data.
B They set screen display color and intensity attributes.
Reserved Lines
On the 4GL screen, certain lines are reserved for output from specic 4GL
statements or fromother sources. By default, these reserved lines appear in the
following positions on the 4GL screen:
B Menu line. Line 1 displays the menu title and options list from
MENU.
B Prompt line. Line 1 also displays text specied by the PROMPT
statement.
B Menu Help line. Line 2 displays text describing MENU options. You
cannot reposition this line independently of the Menu line.
B Message line. Line 2 also displays text fromthe MESSAGE statement.
You can reposition this line with the OPTIONS statement.
B Form line. Line 3 begins a form display when DISPLAY FORM
executes.
B Comment line. The next-to-last line of the 4GL screen (or the last line
in a 4GL window) displays COMMENTS attribute messages.
B Error line. The last line of the 4GL screen displays output from the
ERROR statement.
2-28 INFORMIX- 4GL Reference Manual
4GL Wi ndows
If you display the form in a named 4GL window, these default values apply
to that window, rather than to the 4GL screen, except for the Error line. (The
position of the Error line is dened relative to the entire screen, rather than to
any 4GL window.)
The OPTIONS statement can change these default positions for all the 4GL
windows of your application. The OPEN WINDOW statement can reposition
all of these reserved lines (except the Error line) within the specied 4GL
window. (These 4GL statements are described in detail in Chapter 4.)
4GL Windows
A 4GL window is a named rectangular area on the 4GL screen. When a 4GL
program starts, the entire 4GL screen is the current window. Some 4GL state-
ments can reference this default window as SCREEN. The OPEN WINDOW
statement can create additional 4GL windows, dimensions, position, and
attributes of each window. In DBMS applications that performvarious tasks,
displaying distinct activities in different 4GL windows is a good design
strategy.
No 4GL window can display more than one 4GL form. The CURRENT
WINDOW statement can transfer control from one 4GL window to another.
The Current Window
4GL maintains a list of all open 4GL windows, called the window stack. When
you open a new4GL window, it is added to the top of this stack. The window
at the top of the stack is the current window.
The current 4GL windowis always completely visible, and can obscure all or
part of other windows. When you specify a newcurrent window, 4GL adjusts
the windowstack by moving that windowto the top, and closing any gap in
the stack left by the window. When you close a window, 4GL removes that
window from the window stack. The top-most window among those that
remain on the screen becomes the current window. All this takes place within
the 4GL screen.
The INFORMIX- 4GL Language 2-29
On- Li ne Hel p
All input and output is done in the current window. If that windowcontains
a screen form, the form becomes the current form. The DISPLAY ARRAY,
INPUT, INPUT ARRAY, and MENU statements all run in the current window.
If a user displays a form in another window from within one of these
statements (for example, by activating an ON KEY block), the window
containing the new form becomes the current window. When the enclosing
statement resumes execution, the original windowis restored as the current
window.
Programs with multiple windows might need to switch to a different current
window unconditionally, so that input and output occur in the appropriate
window. The CURRENT WINDOW statement makes a specied window (or
SCREEN) the current window. When a windowbecomes the current window,
4GL restores its values for the positions of the Prompt, Menu, Message, Form,
and Comment lines.
On-Line Help
4GL includes two distinct facilities for displaying help messages:
B Development help. The developer can request help from the
Programmers Environment regarding features of the 4GL language.
Use the Help key (typically CONTROL-W) to display help on the
currently selected menu option.
B Runtime help. The user of a 4GL application can display
programmer-dened help messages.
Runtime help is displayed when the user presses a designated Help key
(CONTROL-W). The 4GL statements that can include a HELP clause are these:
B CONSTRUCT (during a query by example)
B INPUT and INPUT ARRAY (during data entry)
B MENU (for each menu option)
B PROMPT (when the user must supply keyboard input)
The HELP clause species a single help message for the entire 4GL statement.
To provide eld-level help in these interactive statements, you can use an ON
KEY clause with the INFIELD( ) operator and the SHOW_HELP( ) function,
which are described in Chapter 5, Built-In Functions and Operators.
2-30 INFORMIX- 4GL Reference Manual
On- Li ne Hel p
The Help Key and the Message Compiler
By default, CONTROL-Wacts as the Help key. To specify a nondefault Help key,
or to identify a le that contains help messages, use the OPTIONS statement.
If you specify a le of help messages, 4GL displays the messages in the Help
window.
The Help Window
Here is an example of a typical Help window display.
When the user presses the Help key in a context for which you have prepared
a help message, that message appears in a Help window. The 4GL screen is
hidden while this window is open.
The Helpwindowhas a 4GL ring menucontaining ScreenandResume menu
options. Screen displays the next page of help text. Resume closes the Help
window and redisplays the 4GL screen.
HELP: Screen Resume
Ends this Help session.
____________________________________________________________________
To delete a customer from the database, first use the
query function to find the customer row you want to
delete. Then select the delete option and type "y" to
delete the row or "n" if you decide not to delete the row.
You have reached the end of this help text. Press RETURN to continue.
The INFORMIX- 4GL Language 2-31
Nested and Recursi ve Statements
You must create these help messages and store them in an ASCII le. Each
message begins with a unique whole number that has an absolute value no
greater than 32,767 and is prexed by a period ( . ). Statements of 4GL can
reference a help message by specifying its number in a HELP clause.
You must compile help messages from the ASCII source le to a runtime
format by using the mkmessage utility. For more information about creating
help messages, see The mkmessage Utility on page B-2.
The Help window persists until the user closes it. The user can dismiss the
Help window by using the Resume menu option or by pressing RETURN.
Nested and Recursive Statements
The form-based 4GL statements CONSTRUCT, DISPLAY ARRAY, INPUT,
INPUT ARRAY, and PROMPT are collectively referred to as input control block
(ICB) statements, because they use a common underlying data structure
called the input control block. 4GL supports nested and recursive ICB state-
ments in which the parent and the child ICB statements use the same screen
form for accepting and displaying data. In the case of recursive ICB state-
ments, the parent and the child statements can be the same:
B Nested input occurs when two ICB statements (such as INPUT, INPUT
ARRAY, DISPLAY ARRAY, or CONSTRUCT) operate concurrently on
the same elds of the same screen form. Concurrently, in this context,
means that one ICB statement is suspended while using the same
form eld that another ICB statement is using.
B Recursive input occurs when two instances of the same ICB statement
operate concurrently, and a BEFORE or AFTER or ON KEY control
block is activated that invokes a function that executes the same ICB
statement recursively, re-executing that ICB statement. It does not
matter whether the recursion is direct (the function calls itself) or
indirect (the function calls another function, which in turn calls the
rst function again).
Opening and closing screen forms precludes nesting and recursion of ICB
statements, which can only occur when forms are not being opened and
closed while the outer ICB statement is still processing.
Recursive andnestedinput imply the use of the same 4GL window. Changing
the current windowinherently changes the form(or the instance of the form)
that is currently in use.
2-32 INFORMIX- 4GL Reference Manual
Nested and Recursi ve Statements
4GL supports both direct and indirect nesting of the ICB statements; the level
of nesting is limited only by the availability of the resources. Direct nesting
involves embedding the child ICB statement in a control block, such as ON
KEY, BEFORE FIELD, AFTER FIELD, and so forth, of the parent ICB statement.
The following code example illustrates direct nesting of INPUT statements:
MAIN
DEFINE r1, r2 RECORD
f1, f2, f3 CHAR(30)
END RECORD
DATABASE nestedinputDB
DEFER INTERRUPT
OPEN FORM nest_form FROM "nested_input"
DISPLAY FORM nest_form
LET INT_FLAG = FALSE
IF NOT INT_FLAG THEN
INPUT BY NAME r1.* WITHOUT DEFAULTS --Parent INPUT stmt
BEFORE INPUT
MESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1
BEFORE FIELD f1
MESSAGE "Input Statement 1 -- BF1" SLEEP 1
AFTER FIELD f2
MESSAGE "Input Statement 1 -- AF1" SLEEP 1
--Child INPUT Statement
INPUT BY NAME r2.* WITHOUT DEFAULTS --Child INPUT stmt
BEFORE INPUT
MESSAGE "BEFORE INPUT STATEMENT 2" SLEEP 1
AFTER INPUT
MESSAGE "AFTER INPUT STATEMENT 2" SLEEP 1
ON KEY (CONTROL-W)
MESSAGE "IP2: HELP IS NOT AVAILABLE" SLEEP 1
END INPUT --End of Child INPUT stmt
LET r2.f1 = "Child INPUT Statement -- ", r2.f1 CLIPPED
INSERT INTO table_2 VALUES(r2.*)
AFTER INPUT
MESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1
ON KEY (CONTROL-W)
MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1
END INPUT --End of Parent INPUT stmt
END IF
LET r.f1 = "Parent INPUT Statement -- ", r1.f1 CLIPPED
INSERT INTO table_1 VALUES(r1.*)
MESSAGE "Input Statement -- complete" SLEEP 1
END MAIN
The INFORMIX- 4GL Language 2-33
Nested and Recursi ve Statements
In this example of nested INPUT statements, the parent and the child state-
ments use the same formfor entering data. After the user enters data in elds
f1 and f2 for the parent INPUT statement, control transfers to the child INPUT
statement. Once the child INPUT statement is executed, data entered for the
child is inserted in table_2. Then control returns to the parent and elds f1
and f2 are restored to their original values.
Indirect nesting invokes a function that contains the child ICB statement,
fromthe parent ICB statement. Once again, the parent and the child ICB state-
ments use the same form for data entry.
The following code illustrates indirect nesting of INPUT statements:
MAIN
DEFINE r1 RECORD
f1, f2, f3 CHAR(30)
END RECORD
DATABASE nestedinputDB
DEFER INTERRUPT
OPEN FORM nest_form FROM "nested_input"
DISPLAY FORM nest_form
LET INT_FLAG = FALSE
IF NOT INT_FLAG THEN
INPUT BY NAME r1.* WITHOUT DEFAULTS--Parent INPUT stmt
BEFORE INPUT
MESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1
BEFORE FIELD f1
MESSAGE "Input Statement 1 -- BF1" SLEEP 1
AFTER FIELD f2
MESSAGE "Input Statement 1 -- AF1" SLEEP 1
--Indirect Nesting
CALL child_inputstmt()
AFTER INPUT
MESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1
ON KEY (CONTROL-W)
MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1
END INPUT --End of Parent INPUT stmt
END IF
LET r.f1 = "Parent INPUT Statement -- ", r1.f1 CLIPPED
INSERT INTO table_1 VALUES(r1.*)
MESSAGE "Input Statement -- complete" SLEEP 1
END MAIN
FUNCTION child_inputstmt()
DEFINE r2 RECORD
f1, f2, f3 CHAR(30)
END RECORD
LET INT_FLAG = FALSE
IF NOT INT_FLAG THEN
INPUT BY NAME r2.* WITHOUT DEFAULTS --Child INPUT stmt
BEFORE INPUT
MESSAGE "BEFORE INPUT STATEMENT 2" SLEEP 1
2-34 INFORMIX- 4GL Reference Manual
Nested and Recursi ve Statements
AFTER INPUT
MESSAGE "AFTER INPUT STATEMENT 2" SLEEP 1
ON KEY (CONTROL-W)
MESSAGE "IP2: HELP IS NOT AVAILABLE" SLEEP 1
END INPUT --End of Child INPUT stmt
END IF
LET r2.f1 = "Child INPUT Statement -- ", r2.f1 CLIPPED
INSERT INTO table_2 VALUES(r2.*)
END FUNCTION
Performing heterogeneous nesting is valid where the parent and the child
statements are entirely different. For example, where CONSTRUCT is the
parent statement, INPUT can be the child statement.
The recursive ICB statements feature provides extra exibility to 4GL
programmers. The following example illustrates the use of the recursive
INPUT statement:
MAIN
DEFINE r RECORD
f1, f2, f3 CHAR(30)
END RECORD
DEFINE z INTEGER
DATABASE recinputDB
DEFER INTERRUPT
OPEN FORM recurs_form FROM "recursive_input"
DISPLAY FORM recurs_form
LET z = 0
CALL recursive_input(z, r)
END MAIN
FUNCTION recursive_input(z1, r1)
DEFINE r1 RECORD
f1, f2, f3 CHAR(30)
END RECORD
DEFINE z1 INTEGER
LET INT_FLAG = FALSE
LET z1 = z1 + 1
IF z1 > 3 THEN
RETURN
END IF
MESSAGE "Recursive Cycle: ", z1 SLEEP 1
IF NOT INT_FLAG THEN
INPUT BY NAME r1.* WITHOUT DEFAULTS
BEFORE INPUT
MESSAGE "BEFORE INPUT STATEMENT 1" SLEEP 1
BEFORE FIELD f1
MESSAGE "Input Statement 1 -- BF1" SLEEP 1
AFTER FIELD f2
MESSAGE "Input Statement 1 -- AF1" SLEEP 1
The INFORMIX- 4GL Language 2-35
Nested and Recursi ve Statements
CALL recursive_input(z1, r1) --Recursive call
AFTER INPUT
MESSAGE "AFTER INPUT STATEMENT 1" SLEEP 1
ON KEY (CONTROL-W)
MESSAGE "IP1: HELP IS NOT AVAILABLE" SLEEP 1
END INPUT
END IF
LET r.f1 = "Recursive Cycle -- ", z1, r1.f1 CLIPPED
INSERT INTO table_1 VALUES(r1.*)
MESSAGE "Input Statement -- complete" SLEEP 1
END FUNCTION
For every recursive invocation of the function recursive_input( ), the same
form is used for data entry. A recursive call is made after you enter data in
elds f1 and f2 for each invocation. Before making a recursive call, the
context is stored in dynamically allocated variables and pushed onto a stack.
After the terminating condition for recursion is satised, the context is
popped out of the stack, and the buffers for elds f1 and f2 revert to their
original values.
It is valid to combine all the different types of nesting, such as direct, indirect,
heterogeneous, and homogeneous, with recursive ICB statements. To avoid
anomalous behavior, it is advisable to recompile and relink pre-6.x 4GL
applications that use ICB-related statements with current 4GL software.
Early Exits from Nested and Recursive Operations
These nested input features allow some operations that can cause
4GL to clean up incorrectly during INPUT, INPUT ARRAY, DISPLAY ARRAY,
CONSTRUCT, MENU, and PROMPT statements, and in FOREACH loops.
For any nested statements, an early exit from inside one of the inner state-
ments to one of the outer statements, or a RETURN, means that 4GL does not
clean up any statement except the innermost statement.
The following code example, though of no practical use, illustrates nested
INPUT statements. There are nine levels of nested statements in the code.
MAIN
CALL f()
END MAIN
FUNCTION f()
DEFINE s CHAR(300)
DEFINE y INTEGER
DEFINE i INTEGER
2-36 INFORMIX- 4GL Reference Manual
Nested and Recursi ve Statements
DEFINE t INTEGER
DEFINE a ARRAY[10] OF INTEGER
DECLARE c CURSOR FOR
SELECT Tabid FROM Systables
OPEN WINDOW w AT 1, 1 WITH FORM "xxx"
LET y = 0
FOREACH c INTO t
FOR i = 1 TO 10
WHILE y < 1000
MENU "ABCDEF"
BEFORE MENU
HIDE OPTION "B"
COMMAND "A" "Absolutely"
SHOW OPTION "B"
IF a[1] THEN EXIT MENU END IF
IF a[1] THEN CONTINUE MENU END IF
NEXT OPTION "E"
COMMAND "B" "Beautiful"
MESSAGE "Thank you"
COMMAND "C" "Colourful"
MESSAGE "Thank you"
COMMAND "D" "Delicious"
MESSAGE "Thank you"
COMMAND "E" "Exit"
EXIT MENU
COMMAND "F"
MENU "XYZ"
COMMAND "X"
EXIT MENU
COMMAND "Y"
INPUT BY NAME y WITHOUT DEFAULTS
AFTER FIELD y
IF a[1] THEN EXIT FOR END IF
IF a[1] THEN CONTINUE FOR END IF
IF a[1] THEN EXIT FOREACH END IF
IF a[1] THEN CONTINUE FOREACH END IF
IF a[1] THEN EXIT WHILE END IF
IF a[1] THEN CONTINUE WHILE END IF
IF a[1] THEN RETURN END IF
IF a[1] THEN EXIT MENU END IF
IF a[1] THEN CONTINUE MENU END IF
IF a[1] THEN EXIT INPUT END IF
IF a[1] THEN CONTINUE INPUT END IF
IF a[1] THEN GOTO End_Label END IF
IF a[1] THEN GOTO Mid_Label END IF
CONSTRUCT BY NAME s ON y
AFTER FIELD y
IF a[1] THEN EXIT FOR END IF
IF a[1] THEN CONTINUE FOR END IF
The INFORMIX- 4GL Language 2-37
Nested and Recursi ve Statements
IF a[1] THEN EXIT FOREACH END IF
IF a[1] THEN CONTINUE FOREACH END IF
IF a[1] THEN EXIT WHILE END IF
IF a[1] THEN CONTINUE WHILE END IF
IF a[1] THEN RETURN END IF
IF a[1] THEN EXIT MENU END IF
IF a[1] THEN CONTINUE MENU END IF
-- EXIT INPUT is not allowed by the compiler (error 4488)
-- IF a[1] THEN EXIT INPUT END IF
-- CONTINUE INPUT is not allowed by the compiler
-- (error 4488)
-- IF a[1] THEN CONTINUE INPUT END IF
IF a[1] THEN EXIT CONSTRUCT END IF
IF a[1] THEN CONTINUE CONSTRUCT END IF
IF a[1] THEN GOTO End_Label END IF
IF a[1] THEN GOTO Mid_Label END IF
CALL SET_COUNT(3)
DISPLAY ARRAY a TO a.*
ON KEY (F3)
IF a[1] THEN EXIT FOR END IF
IF a[1] THEN CONTINUE FOR END IF
IF a[1] THEN EXIT FOREACH END IF
IF a[1] THEN CONTINUE FOREACH END IF
IF a[1] THEN EXIT WHILE END IF
IF a[1] THEN CONTINUE WHILE END IF
IF a[1] THEN RETURN END IF
IF a[1] THEN EXIT MENU END IF
IF a[1] THEN CONTINUE MENU END IF
IF a[1] THEN EXIT DISPLAY END IF
-- CONTINUE DISPLAY is not allowed by the compiler
-- IF a[1] THEN CONTINUE DISPLAY END IF
-- EXIT INPUT is not allowed by the compiler (error 4488)
-- IF a[1] THEN EXIT INPUT END IF
-- CONTINUE INPUT is not allowed by the compiler (error
-- 4488)
-- IF a[1] THEN CONTINUE INPUT END IF
-- EXIT CONSTRUCT is not allowed by the compiler (error
-- 4488)
-- IF a[1] THEN EXIT CONSTRUCT END IF
-- CONTINUE CONSTRUCT is not allowed by the compiler
-- (error 4488)
-- IF a[1] THEN CONTINUE CONSTRUCT END IF
IF a[1] THEN GOTO End_Label END IF
IF a[1] THEN GOTO Mid_Label END IF
INPUT ARRAY a FROM a.*
AFTER FIELD y
IF a[1] THEN EXIT FOR END IF
IF a[1] THEN CONTINUE FOR END IF
IF a[1] THEN EXIT FOREACH END IF
2-38 INFORMIX- 4GL Reference Manual
Nested and Recursi ve Statements
IF a[1] THEN CONTINUE FOREACH END IF
IF a[1] THEN EXIT WHILE END IF
IF a[1] THEN CONTINUE WHILE END IF
IF a[1] THEN RETURN END IF
IF a[1] THEN EXIT MENU END IF
IF a[1] THEN CONTINUE MENU END IF
IF a[1] THEN EXIT INPUT END IF
IF a[1] THEN CONTINUE INPUT END IF
-- EXIT DISPLAY *is* allowed by the compiler (despite
-- error 4488)
IF a[1] THEN EXIT DISPLAY END IF
-- CONTINUE DISPLAY is not allowed by the compiler
-- IF a[1] THEN CONTINUE DISPLAY END IF
-- EXIT CONSTRUCT is not allowed by the compiler (error
-- 4488)
-- IF a[1] THEN EXIT CONSTRUCT END IF
-- CONTINUE CONSTRUCT is not allowed by the compiler
-- (error 4488)
-- IF a[1] THEN CONTINUE CONSTRUCT END IF
IF a[1] THEN GOTO End_Label END IF
IF a[1] THEN GOTO Mid_Label END IF
LABEL Mid_label:
MESSAGE "You got here? How?"
NEXT FIELD y
END INPUT
END DISPLAY
END CONSTRUCT
END INPUT
COMMAND "Z"
MESSAGE "Sucker!"
CONTINUE MENU
END MENU
END MENU
END WHILE
END FOR
END FOREACH
LET y = 0
LABEL End_label:
CLOSE WINDOW w
END FUNCTION
The INFORMIX- 4GL Language 2-39
Excepti on Handl i ng
This example illustrates some problems that early exits fromnested ICB and
MENU statements can cause. For example, when EXIT FOREACH executes
from within an INPUT statement that itself is nested within two MENU state-
ments, a FOR loop, and a WHILE loop (as in the rst EXIT FOREACHstatement
of the previous example), then the intervening menus (ABCDEF and XYZ) are
not cleaned up correctly. Here the INPUT statement itself is handled correctly,
however, and the database cursor in the FOREACH loop closes correctly.
Jump statements, including GOTOand WHENEVERGOTOalso are not dealt
with properly. If this is a concern, do not use GOTO in contexts like this.
Exception Handling
4GL provides facilities for issuing compile-time and link-time detection of
compilation errors, and for detection and handling of warnings and runtime
errors and that occur during program execution.
Compile-Time Errors and Warnings
This manual describes 4GL language syntax, violations of which can cause
compilation errors. Compilation and link-time errors can also result from
improper settings of environment variables, or from invalid SQL syntax.
These topics are described in the Informix Guide to SQL manuals.
If you do not understand an error or warning message, look up its numeric
code with the nderr utility, or look in the on-line documentation of your
Informix database server, or in your network software manual.
Runtime Errors and Warnings
Chapter 12, Handling Exceptions, of Concepts and Use provides an
overviewof runtime errors and the 4GL facilities for handling them. (See also
the built-in STARTLOG( ) and ERRORLOG( ) functions described in Chapter 5,
Built-In Functions and Operators,of the present manual; these can support
automatic or explicit logging of runtime errors in a le.)
By default, runtime errors and warnings are written to stderr. (Versions of
4GL earlier than 6.0 wrote runtime errors and warnings to stdout.)
2-40 INFORMIX- 4GL Reference Manual
Runti me Errors and Warni ngs
There are several types of runtime errors and warnings:
B SQL errors, warnings, or NOTFOUND conditions that the database
server detects and records in the SQLCA area; see Error Handling
with SQLCA on page 2-44
B SPL (Stored Procedure Language) errors that the database server
reports during execution of a stored procedure; see Informix Guide to
SQL: Syntax
B Interrupt, Quit, or other signals from the user or from other sources
B Runtime errors and warnings that 4GL issues
For errors that occur in stored procedures, you can use the ON EXCEPTION
statement of SPL to trap errors within the procedure. You can use the DEFER
statement of 4GL to trap and handle Interrupt and Quit signals, and you can
use WHENEVER to trap and handle SQL and 4GL errors and warnings.
The WHENEVER statement can control the processing of exceptional condi-
tions of several kinds: SQL warnings, SQL end-of-data errors, errors in SQL or
screen I/O operations, or errors in evaluating 4GL expressions.
The DEFER statement can instruct 4GL not to terminate the program when a
user presses the Interrupt or Quit key. The DEFER statement has dynamic
scope, as opposed to the lexical scope of WHENEVER. When Quit or Interrupt
is deferred, the signal is ignored globally (that is, in all modules).
See the descriptions of DEFERandWHENEVERin Chapter 4 for details of how
to use these statements to handle signals, errors, and warnings.
Normal and AnyError Scope
The termerror scope refers to whether the scope of error handling includes
expression errors. Normal error scope includes SQL errors, validation errors
discovered by the VALIDATE statement, and screen interaction statement
errors, but it ignores expression errors. Expression errors neither initiate any
action by a WHENEVER statement, nor do they set the status variable when
Normal error scope is in effect.
The INFORMIX- 4GL Language 2-41
Runti me Errors and Warni ngs
In contrast, AnyError error scope means that expression errors also activate
error logic, and status is set to an appropriate negative value after the
statement that produced the expression error. This was the only error scope
available with Version 4.0 of 4GL. In the current release, however, you must
request it explicitly with the WHENEVER ANY ERROR directive or with the -
anyerr ag when you compile or in the RDS runner or Debugger command
line.
For maximumease in preventing, locating, and correcting expression errors,
Informix recommends that you write all new4GL code to work under
AnyError error scope. With 4GL programs that you compile to C, you can
achieve this automatically by setting the C4GLFLAGS environment variable
to include -anyerr. With RDS, you can achieve this by setting the
FGLPCFLAGS environment variable to include -anyerr.
A Taxonomy of Runtime Errors
The WHENEVER statement classies 4GL runtime errors into four disjunct
categories, as shown in Figure 2-5.
Here errors of type 1 occur on the database server, and reset the built-in
SQLCA.SQLCODE variable to a negative value. (See Error Handling with
SQLCA on page 2-44 for a description of SQLCA.SQLCODE.)
To trap errors of types 1, 2, and 3, which correspond to Normal error scope,
specify WHENEVER ERROR. As Figure 2-5 indicates, Normal error scope is a
logical subset of AnyError error scope.
Figure 2-5
Categories of
Runtime Errors
4GL errors
1 2 3 4
Normal Error Scope
AnyError Error Scope
SQL
errors
Screen I/ O
errors
Val i dati on
errors
Eval uati on
errors
2-42 INFORMIX- 4GL Reference Manual
Runti me Errors and Warni ngs
To use AnyError error scope, which can also trap errors of type 4, you must
specify WHENEVER ANY ERROR, or else compile with the -anyerr option.
Errors of type 4 can include arithmetic, Boolean, or conversion errors that
occur when 4GL evaluates an expression.
Important: Earlier releases of 4GL supported fatal (or untrappable) runtime
errors, which could not be trapped by WHENEVER statements, but such errors are
not a feature of this release. There are no 4GL errors outside AnyError error scope.
4GL runtime errors are included in Informix Error Messages in Answers
OnLine.
Default Error Behavior and ANSI Compliance
The default responses to error conditions differ between the ANSI-compliant
method and the non-ANSI-compliant method as follows:
1. If ANSI compliance is requested and no WHENEVER statement is in
effect, the default action after an error is CONTINUE.
ANSI compliance is in effect if any of the following conditions exists:
B There is a default compile-time database that is ANSI-compliant.
B The -ansi compilation ag is specied.
B The DBANSIWARN environment variable is set.
In releases of RDS earlier than 6.0, the default error action was STOP
(rather than CONTINUE) for the last two of these three conditions.
2. If neither ANSI compliance nor any WHENEVERstatement is ineffect,
the following factors determine the default error action:
B If the -anyerr ag is used, the default action is STOP.
B If the -anyerr ag is not used, the default action after an
expression or data type conversion error is CONTINUE. After
other categories of errors, it is STOP.
ANSI
The INFORMIX- 4GL Language 2-43
Changes to 4GL Error Handl i ng
The error behavior depends on the database that the nonprocedural
DATABASE statement references when you compile the program. If you
compile with a non-ANSI-compliant default database, but run with an ANSI-
compliant current database, the error behavior is as if the database were not
an ANSI-compliant database. The converse also applies: if you compile
against an ANSI-compliant database but run against a non-ANSI-compliant
database, then the error behavior is the same as if the runtime database were
ANSI-compliant.
If you compile part of the application against an ANSI-compliant database
and part of it against a non-ANSI-compliant database, then those parts of the
application compiled against the ANSI-compliant database have the default
error action of CONTINUE and those parts compiled against the non-ANSI-
compliant database have the default error action of STOP.
Changes to 4GL Error Handling
In this version of 4GL (and in contrast to versions earlier than 6.01), the
following error handling features are in effect:
B The status variable is set for expression errors only if AnyError error
scope is in effect. AnyError behavior is no longer the default for RDS.
This is a signicant backward-compatibility concern for RDS users
who do not explicitly use AnyError error scope. Use the -anyerr ag
when compiling your p-code modules to prevent unexpected failure
of expression errors to set status (and recompile other p-code
modules in the same program, for consistency within each program).
B Error and warning messages are no longer written to the UNIX
standard error le. They are written to the 4GL error log le only.
This change primarily affects 4GL programs that are compiled to C and that
use Normal error scope (because most RDS expression or conversion errors
have used -anyerr behavior, regardless of the requested error scope). Use 4GL
error logs in order to recognize and isolate errors.
2-44 INFORMIX- 4GL Reference Manual
Error Handl i ng wi th SQLCA
Error Handling with SQLCA
Proper database management requires that all logical sequences of
statements that modify the database continue successfully to completion.
Suppose, for example, that an UPDATE operation on a customer account
shows a reduction of $100.00 in the payable balance, but for some reason the
next step, an UPDATE of the cash balance, fails; now your books are out of
balance. It is prudent to verify that every SQL statement executes as you
anticipated. 4GL provides two ways to do this:
B The global variable status, which can indicate errors, both fromSQL
statements and from other 4GL statements
B The global record SQLCA, which indicates the success of SQL
statements, and provides other information about actions of the
database server
Compared to status, the SQLCA.SQLCODE variable is typically easier to use
for monitoring the success or failure of SQL statements because it ignores
exceptional conditions that might be encountered in other 4GL statements.
4GL returns a result code into the SQLCA record after executing every SQL
statement. Because it is automatically dened, you do not need to (and must
not) declare the SQLCA record, which has this structure:
DEFINE SQLCA RECORD
SQLCODE INTEGER,
SQLERRM CHAR(71),
SQLERRP CHAR(8),
SQLERRD ARRAY [6] OF INTEGER,
SQLAWARN CHAR (8)
END RECORD
The INFORMIX- 4GL Language 2-45
Error Handl i ng wi th SQLCA
The members of SQLCA have the following semantics:
SQLCODE indicates the result of any SQL statement. It is set to zero for a
successful execution, and to NOTFOUND( = 100 ) for a success-
fully executed query that returns zero rows, or for a FETCH
that seeks beyond the end of the current active set. SQLCODE
is negative after an unsuccessful SQL operation.
At runtime, 4GL sets the variable status equal to SQLCODE
after each SQL statement. (See also the description of the ANY
keyword of WHENEVER in A Taxonomy of Runtime Errors
on page 2-41.) The nderr utility can provide explanations of
SQL and 4GL error codes.
SQLERRM is not used at this time.
SQLERRP is not used at this time.
SQLERRD is an array of six variables of data type INTEGER:
SQLERRD[1] is not used at this time.
SQLERRD[2] is a SERIAL value returned or ISAMerror code.
SQLERRD[3] is the number of rows inserted or updated.
SQLERRD[4] is the estimated CPU cost for query.
SQLERRD[5] is the offset of the error into the SQL statement.
SQLERRD[6] is the rowID of the last row that was
processed; whether it was returned is server
dependent.
SQLAWARN is an 8-byte string whose characters signal any warnings (as
opposed to errors) after any SQL statement executes. All
characters are blank if no problems were detected.
SQLAWARN[1] is set to W if any of the other warning characters
were set to W. If SQLAWARN[1] is blank, you do
not have to check the other warning
characters.
SQLAWARN[2] is set to W if one or more values were truncated
to t into a CHAR variable, or if a DATABASE
statement selected a database with
transactions.
2-46 INFORMIX- 4GL Reference Manual
Error Handl i ng wi th SQLCA
If a multi-rowINSERT or UPDATE statement of SQL fails, then SQLERRD[3] is
set to the number of rows that were processed before the error was detected.
If a LOAD operation fails with error -846, however, SQLERRD[3] is always set
to 1, regardless of how many rows (if any) were successfully inserted.
For a complete description of SQLCA, see the Informix Guide to SQL: Tutorial
in your Informix database server documentation.
SQLAWARN[3] is set to W if an aggregate like SUM( ), AVG( ),
MAX( ), or MIN( ) encountered a null value in
its evaluation, or if the DATABASE statement
specied an ANSI/ISO-compliant database.
SQLAWARN[4] is set to W if a DATABASE statement selected an
Informix Dynamic Server database, or when
the number of items in the select-list of a
SELECT clause is not the same as the number of
program variables in the INTO clause. (The
number of values returned by 4GL is the
smaller of these two numbers.)
SQLAWARN[5] is set to W if oat-to-decimal conversion is
used.
SQLAWARN[6] is set to W if your programexecutes anInformix
extension to the ANSI/ISO standard for SQL
syntax while the DBASIWARN variable is set,
or after the -ansi compilation ag was used.
SQLAWARN[7] is set to W if a query skips a table fragment, or
if the database and client have different
locales.
SQLAWARN[8] is not used at present.
3
Chapter
Data Types and Expressions
In This Chapter . . . . . . . . . . . . . . . . . . . . 3-5
Data Values in 4GL Programs . . . . . . . . . . . . . . . 3-5
Data Types of 4GL . . . . . . . . . . . . . . . . . . . 3-6
Simple Data Types. . . . . . . . . . . . . . . . . . 3-9
Number Data Types . . . . . . . . . . . . . . . 3-10
Character Data Types . . . . . . . . . . . . . . 3-11
Time Data Types . . . . . . . . . . . . . . . . 3-11
Structured Data Types . . . . . . . . . . . . . . . . 3-12
Large Data Types . . . . . . . . . . . . . . . . . . 3-12
Descriptions of the 4GL Data Types . . . . . . . . . . . . 3-12
ARRAY . . . . . . . . . . . . . . . . . . . . . 3-13
BYTE . . . . . . . . . . . . . . . . . . . . . . 3-14
CHAR . . . . . . . . . . . . . . . . . . . . . . 3-15
CHARACTER . . . . . . . . . . . . . . . . . . . 3-17
DATE . . . . . . . . . . . . . . . . . . . . . . 3-17
DATETIME . . . . . . . . . . . . . . . . . . . . 3-18
DEC . . . . . . . . . . . . . . . . . . . . . . 3-23
DECIMAL (p, s) . . . . . . . . . . . . . . . . . . 3-23
DECIMAL (p) . . . . . . . . . . . . . . . . . . . 3-24
DOUBLE PRECISION . . . . . . . . . . . . . . . . 3-25
FLOAT. . . . . . . . . . . . . . . . . . . . . . 3-25
INT . . . . . . . . . . . . . . . . . . . . . . . 3-26
INTEGER. . . . . . . . . . . . . . . . . . . . . 3-26
INTERVAL . . . . . . . . . . . . . . . . . . . . 3-27
MONEY . . . . . . . . . . . . . . . . . . . . . 3-32
NUMERIC . . . . . . . . . . . . . . . . . . . . 3-33
REAL . . . . . . . . . . . . . . . . . . . . . . 3-33
3-2 INFORMIX- 4GL Reference Manual
RECORD . . . . . . . . . . . . . . . . . . . . . 3-34
SMALLFLOAT . . . . . . . . . . . . . . . . . . . 3-36
SMALLINT . . . . . . . . . . . . . . . . . . . . 3-37
TEXT . . . . . . . . . . . . . . . . . . . . . . 3-38
VARCHAR . . . . . . . . . . . . . . . . . . . . 3-39
Data Type Conversion . . . . . . . . . . . . . . . . 3-41
Converting from Number to Number . . . . . . . . . . 3-41
Converting Numbers in Arithmetic Operations . . . . . . 3-42
Converting Between DATE and DATETIME . . . . . . . 3-43
Converting CHAR to DATETIME or INTERVAL Data Types . . 3-44
Converting Between Number and Character Data Types . . . 3-45
Converting Large Data Types. . . . . . . . . . . . . 3-45
Summary of Compatible 4GL Data Types . . . . . . . . . . 3-45
Notes on Automatic Data Type Conversion . . . . . . . . 3-47
Expressions of 4GL . . . . . . . . . . . . . . . . . 3-49
Differences Between 4GL and SQL Expressions . . . . . . . . 3-50
Components of 4GL Expressions . . . . . . . . . . . . . 3-52
Parentheses in 4GL Expressions . . . . . . . . . . . . 3-52
Operators in 4GL Expressions . . . . . . . . . . . . 3-53
Operands in 4GL Expressions . . . . . . . . . . . . 3-56
Named Values as Operands . . . . . . . . . . . . . 3-57
Function Calls as Operands . . . . . . . . . . . . . 3-58
Expressions as Operands . . . . . . . . . . . . . . 3-59
Boolean Expressions . . . . . . . . . . . . . . . . . 3-60
Logical Operators and Boolean Comparisons . . . . . . . 3-61
Data Type Compatibility . . . . . . . . . . . . . . 3-61
Evaluating Boolean Expressions . . . . . . . . . . . . 3-62
Integer Expressions . . . . . . . . . . . . . . . . . 3-63
Binary Arithmetic Operators . . . . . . . . . . . . . 3-64
Unary Arithmetic Operators . . . . . . . . . . . . . 3-65
Literal Integers . . . . . . . . . . . . . . . . . 3-65
Number Expressions . . . . . . . . . . . . . . . . . 3-66
Arithmetic Operators . . . . . . . . . . . . . . . 3-66
Literal Numbers . . . . . . . . . . . . . . . . . 3-67
Character Expressions . . . . . . . . . . . . . . . . 3-68
Arrays and Substrings . . . . . . . . . . . . . . . 3-69
String Operators . . . . . . . . . . . . . . . . . 3-70
Non-Printable Characters . . . . . . . . . . . . . . 3-70
Data Types and Expressi ons 3-3
Time Expressions . . . . . . . . . . . . . . . . . . . 3-72
Numeric Date . . . . . . . . . . . . . . . . . . 3-75
DATETIME Qualier . . . . . . . . . . . . . . . . 3-76
DATETIME Literal . . . . . . . . . . . . . . . . . 3-78
INTERVAL Qualier . . . . . . . . . . . . . . . . 3-80
INTERVAL Literal . . . . . . . . . . . . . . . . . 3-82
Arithmetic Operations on Time Values . . . . . . . . . . 3-83
Relational Operators and Time Values . . . . . . . . . . 3-86
Field Clause . . . . . . . . . . . . . . . . . . . . 3-87
Table Qualiers . . . . . . . . . . . . . . . . . . . 3-90
Owner Naming . . . . . . . . . . . . . . . . . . 3-90
Database References . . . . . . . . . . . . . . . . 3-91
THRU or THROUGH Keywords and .* Notation . . . . . . . 3-93
ATTRIBUTE Clause . . . . . . . . . . . . . . . . . . 3-97
Color and Monochrome Attributes . . . . . . . . . . . 3-98
Precedence of Attributes . . . . . . . . . . . . . . . 3-99
3-4 INFORMIX- 4GL Reference Manual
Data Types and Expressi ons 3-5
In This Chapter
This chapter describes how4GL programs represent data values. The rst
part of this chapter describes the 4GL data types; the latter part describes 4GL
expressions, which can return specic values of these data types.
Data Values in 4GL Programs
This section identies and describes the data types of 4GL. In general, data
values in 4GL must be represented as some data type. A data type is a named
category that describes what kind of information is being stored, and that
implies what kinds of operations on the data value make sense.
In some cases, a value stored as one data type can be converted to another.
Data Type Conversion on page 3-41 identies the pairs of 4GL data types
for which automatic conversion is supported and describes ways in which
information can be lost or modied by such conversion.
A related fundamental concept of 4GL is the notion of an expression. Just
as a data type (such as INTEGER) characterizes a general category of values,
an expression denes a specic data value. Later sections of this chapter
describe howdata values are represented in 4GL source code by expressions,
and classify expressions according to the data type of the returned value.
3-6 INFORMIX- 4GL Reference Manual
Data Types of 4GL
Data Types of 4GL
You must declare a data type for each variable, FORMONLY eld, formal
argument of a function or report, or value returned by a function. Function
and report arguments can be any 4GL data types except ARRAY.
The following data types are valid in declarations of program variables.
Data Type Kinds of Values Stored
ARRAY OF type Arrays of values of any other single 4GL data type
BYTE Any kind of binary data, of length up to 2
31
bytes
CHAR(size) Character strings, of size up to 32,767 bytes in length
CHARACTER This keyword is a synonym for CHAR
DATE Points in time, specied as calendar dates
DATETIME Points in time, specied as calendar dates and time-of-day
DEC This keyword is a synonym for DECIMAL
DECIMAL(p,s)d Fixed-point numbers, of a specied scale and precision
DECIMAL(p) Floating-point numbers, of a specied precision
DOUBLE PRECISION These keywords are a synonym for FLOAT
FLOAT Floating-point numbers, of up to 32-digit precision
INT This keyword is a synonym for INTEGER
INTEGER Whole numbers, from -2,147,483,647 to +2,147,483,647
INTERVAL Spans of time in years and months, or in smaller time units
MONEY Currency amounts, with denable scale and precision
NUMERIC This keyword is a synonym for DECIMAL
REAL This keyword is a synonym for SMALLFLOAT
RECORD Ordered sets of values, of any combination of data types
(1 of 2)
Data Types and Expressi ons 3-7
Data Types of 4GL
Except for ARRAYandRECORD, the 4GL data types correspondto built-in SQL
data types of Informix database servers. The data types of 4GL approximate
a superset of the SQL data types that 7.x Informix database servers recognize,
but with the following restrictions:
B The SERIALdata type of SQL is not a 4GL data type. (Use the INTEGER
data type to store SERIAL values froma database.) Youcannot use the
SERIAL keyword in 4GL statements that are not SQL statements.
B 4GL does not recognize NCHAR or NVARCHAR as data types. When
a 4GL programon a systemin which DBNLS = 1 accesses an Informix
database that includes NCHAR or NVARCHAR columns, retrieved
values from any NCHAR columns are automatically converted to
CHAR values, and CHAR variables can update NCHAR columns.
Similarly, NVARCHAR values from the database are converted to
VARCHAR variables, and values in VARCHAR variables can update
NVARCHAR database columns when DBNLS is set to 1.
B 4GL does not recognize the BITFIXED, BITVARYING, BLOB, BOOLEAN,
CLOB, DISTINCT, INT8, LIST, LVARCHAR, MULTISET, OPAQUE,
REFERENCE, ROW, SERIAL8, SET, or user-dened data types of
Informix database servers.
SMALLFLOAT Floating-point numbers, of up to 16-digit precision
SMALLINT Whole numbers, from -32,767 to +32,767
TEXT Character strings of up to 2
31
bytes
VARCHAR(size) Character strings of varying length, for size 255 bytes
Data Type Kinds of Values Stored
(2 of 2)
3-8 INFORMIX- 4GL Reference Manual
Data Types of 4GL
Declarations of 4GL variables, formal arguments, andreturnedvalues use the
following syntax to specify data types directly.
Declarations of variables can also use the LIKE keyword, as described in
Indirect Typing on page 4-85. TEXT andBYTE are called the large data types;
ARRAY and RECORD are called the structured data types. All other 4GL data
types are simple data types.
Sections that follow describe the 4GL data types in each of these categories.
Simple Data Type
p. 3-9
Structured Data Type
p. 4-89
Large Data Type
p. 4-89
4GL Data Type
Data Types and Expressi ons 3-9
Si mpl e Data Types
Simple Data Types
Each simple data type of 4GL can store a single value whose maximumstorage
requirement is specied or implied in the data type declaration.
scale
DATETIME Qualier
p. 3-76
size
, reserved
DECIMAL
DEC
NUMERIC
FLOAT
DOUBLE PRECISION
precision
SMALLFLOAT
REAL
DATE
DATETIME
CHARACTER
CHAR
Simple Data Type
(16)
MONEY
( )
precision
,
scale
(
( )
(16, 2) )
, 0
size
( )
INTEGER
INT
SMALLINT
( )
precision
( 1 )
, 2
INTERVAL Qualier
p. 3-80
INTERVAL
N
u
m
b
e
r
C
h
a
r
a
c
t
e
r
T
i
m
e
)
) ,
VARCHAR
Element Description
precision is the number of signicant digits. For FLOAT, 1 precision 14.
For DECIMAL and MONEY, the range is 1 precision 32.
reserved is an SQL parameter not used by 4GL; 0 reserved size 255.
scale is the number of digits ( 32) in the fractional part of the number,
where 0 scale precision. The actual scale may be less than 32.
size is the maximum number of bytes that the data type can store.
For CHAR: 1 size 32,767; for VARCHAR: 1 size 255.
3-10 INFORMIX- 4GL Reference Manual
Si mpl e Data Types
All parameters in data type declarations must be specied as literal integers.
(For more information, see Literal Integers on page 3-65.) The precision
term of FLOAT and DOUBLE PRECISION data type declarations, and reserved
in VARCHAR data type declarations, are accepted by 4GL but are ignored.
Each simple data type can be classied as a number, time, or character type.
(Numeric, chronological, and string are synonyms for these categories.)
Number Data Types
4GL supports seven simple data types to store various kinds of numbers.
Number Types Description
Whole Number SMALLINT
INTEGER, INT
Integers, ranging from -32,767 to +32,767
Integers, ranging from -2,147,483,647 to +2,147,483,647
(that is, -(2
31
-1) to (2
31
-1))
Fixed-Point DECIMAL (p, s),
DEC(p, s),
NUMERIC(p, s)
MONEY (p, s)
Fixed-point numbers, of scale s and precision p
Currency values, of scale s and precision p
Floating-Point DECIMAL (p),
DEC(p),
NUMERIC(p)
FLOAT,
DOUBLE PRECISION
SMALLFLOAT, REAL
Floating-point numbers of precisionp (but see DECIMAL
(p) on page 3-24 for information about ANSI-compliant
databases)
Floating-point, double-precision numbers
Floating-point, single-precision numbers
Data Types and Expressi ons 3-11
Si mpl e Data Types
Character Data Types
4GL supports two simple data types for storing character string values.
The TEXT data type (see TEXT on page 3-38) can store text strings of up to
two gigabytes ( = 2
31
bytes). However, TEXT is not classied here as a
character data type because 4GL manipulates TEXT values in a different way
from howVARCHAR or CHAR values are processed.
Time Data Types
4GL supports three simple data types for values in chronological units. Two
store points in time, and the third stores spans of time (positive or negative).
Character Types Description
CHAR ( size ),
CHARACTER ( size )
Strings of length size, for size up to 32,767 bytes
VARCHAR ( size, reserved ) Strings of length size, for size 255 bytes
Time Types Description
DATE Calendar dates (month, day, year) with a xed scale of days, in the
range from January 1 of the year 1 up to December 31, 9999
DATETIME Calendar dates (year, month, day) and time-of-day (hour, minute,
second, and fraction of second), in the range of years 1 to 9999
INTERVAL Spans of time, in years and months, or in smaller units
3-12 INFORMIX- 4GL Reference Manual
Structured Data Types
Structured Data Types
4GL supports two structured data types for storing sets of values.
Large Data Types
Large data types store pointers to binary large objects up to 2
31
bytes (two
gigabytes) or up to a limit imposed by your system resources.
Descriptions of the 4GL Data Types
Sections that followdescribe each of the 4GL data types, in alphabetical order.
Unless otherwise noted, descriptions of formats for data entry and display
are for the default (U.S. English) locale. Some locales support other character
sets and different entry and display formats for number, currency, and date
values, as specied in the locale les and in environment variables.
Structured Types Description
ARRAY Arrays of up to 32,767 values (in up to three dimensions) of any
single data type except ARRAY
RECORD Sets of values of any data type, or any combination of data types
Large Types Description
TEXT Strings of printable characters
BYTE Anything that can be digitized and stored on your system
GLS
Data Types and Expressi ons 3-13
ARRAY
ARRAY
This structured data type stores a one-, two-, or three-dimensional array of
variables, all of the same data type. These variables can be any 4GL data type
except ARRAY. This is the syntax for declaring an array of variables:
Array Elements
Data types are here a subset of those listed in Data Types of 4GL on
page 3-6, because ARRAY is not valid.
Avariable in an array is called an element. You can use bracket ( [ ] ) symbols
and comma-separated integers to reference a single element of an array. For
example, if xray is the identier of an ARRAY variable:
B xray [i] is the ith element of a one-dimensional array.
B xray [i, j] is the jth element in the ith rowof a two-dimensional array.
B xray [i, j, k] is the kth element in the jth column of the ith row of a
three-dimensional array.
Here the coordinates i, j, and k can be variables or other integer expressions
that return positive whole numbers in the range 1 to 32,767. Within an SQL
statement delimited by SQLEND SQL, an ARRAY host variable needs the
dollar sign ($) prex, but a variable used as an index to an array requires no
prex.
Some C compilers impose a limit lower than 32,767 on the number of array
elements in a dimension, or on the total number. (For an array of two or more
dimensions, this total is the product of all the declared size specications.)
Element Description
size is a positive integer number (ranging from1 to 32,767) of elements within
a dimension. Each dimension can have a different size.
ARRAY Data Type
] size
OF
[ 3
4GL Data Type
(subset of p. 3-8)
,
ARRAY
3-14 INFORMIX- 4GL Reference Manual
BYTE
Because you cannot manipulate an array as a single unit, statements must
refer to individual elements of an array. You reference a single array element
by specifying its coordinates in each dimension of the array. For an array with
two dimensions, for example, you must specify two coordinates to reference
any element. In expressions, 4GL expands the identier of a record to a list of
its members but 4GL does not expand the name of an array to its elements.
You cannot pass an array to (or from) a function or report. You can, however,
pass individual array elements. If these elements are records, 4GL expands
each element to its members in the ordinary way. Similarly, if record is a
RECORD having an ARRAY member, record.* is not a valid argument to a
function or to a report, nor (in this case) is record.* a valid specication in a list
of returned values.
Substrings of Character Array Elements
If char_array [i, j, k] is an element of an array of a character data type, you can
use a comma-separated pair of integer expressions between trailing bracket
( [ ] ) symbols to specify a substring within its string value:
char_array [i, j, k] [m, n]
Here m n, for m and n expressions that return positive whole numbers to
specify the respective positions of the rst and last characters of a substring
within the array element whose coordinates in char_array are i, j, and k.
BYTE
The BYTE data type stores any kind of binary data in a structureless byte
stream. Binary data typically consists of saved spreadsheets, program load
modules, digitized voice patterns, or anything that can be stored as digits.
The DEFINE statement can use the LIKE keyword to declare a 4GL variable
like a BYTE column in an Informix database. The INFORMIX-SE database
server does not support BYTE columns, but the 4GL application programcan
declare program variables of the BYTE data type.
The data type BYTE has no maximum size; the theoretical limit is 2
31
bytes,
but the practical limit is determined by the storage capacity of your system.
Data Types and Expressi ons 3-15
CHAR
Youcan use a BYTE variable to store, retrieve, or update the contents of a BYTE
database column, or to reference a le that you wish to display to users of the
4GL programthrough an external editor. After you declare a BYTE data type,
you must use the LOCATE statement to specify the storage location.
When you select a BYTE column, you can assign all or part of it to a variable
of type BYTE. You can use brackets ( [ ] ) and subscripts to reference only part
of a BYTE value, as shown in the following example:
SELECT cat_picture [1,75] INTO cat_nip FROM catalog
WHERE catalog_num = 10001
This statement reads the rst 75 bytes of the cat_picture column of the row
with the catalog number 10001, and stores this data in the cat_nip variable.
(Before running this query, the LOCATE statement must rst be executed to
allocate memory for the cat_nip BYTE variable.)
Restrictions on BYTE Variables
Built-in functions of 4GL cannot have BYTE arguments. Among the operators
of 4GL, only IS NULL and IS NOT NULL can use BYTE variables as operands.
The DISPLAY statement and PRINT statements cannot display BYTE values.
Neither can the LET statement or INITIALIZE statement assign any value
(except null) to a BYTE variable. The CALL and OUTPUT TO REPORT state-
ments pass any BYTE arguments by reference, not by value.
A form eld linked to a BYTE column (or a FORMONLY eld of type BYTE)
displays the character string <BYTE value> rather than actual data. You must
use the PROGRAMattribute to display a BYTE value. No other eld attributes
(except COLOR) can reference the value of a BYTE eld. The upscol utility
cannot set default attributes or default values for a BYTE eld.
CHAR
The CHAR data type of 4GL can store a character string, up to a number of
bytes specied between parentheses in the size parameter of the data type
declaration. These can be printable or non-printable characters (see Non-
Printable Characters on page 3-70), as dened for the locale. The size can
range from 1 to 32,767 bytes.
3-16 INFORMIX- 4GL Reference Manual
CHAR
For example, the variable keystrokes in the following declaration can hold a
character string of up to 78 bytes:
DEFINE keystrokes CHAR(78)
If the size is not specied, the resulting default CHAR data type can store only
a single byte. In a form, you cannot specify the size of a FORMONLY CHAR
eld; the size defaults to the eld length from the screen layout.
A character string returned by a function can contain up to 32,767 bytes. On
INFORMIX-SE servers, the maximumdata string length that a CHAR column
can store is 32,511 bytes, but CHAR variables are not constrained by this.
When a value is passed between a CHAR variable and a CHAR database
column, or between two CHAR variables, exactly size bytes of data are trans-
ferred, where size is the declared length of the 4GL variable or the database
column that receives the string. If the length of the data string is shorter than
size, the string is padded with trailing blanks (ASCII 32) to ll the declared
size. If the string is longer than size, the stored value is truncated.
The ASCII 0 end-of-data character terminates every CHAR value; in most
contexts, any subsequent characters in a data string cannot be retrieved from
or entered into CHAR database columns. Use the CLIPPED operator of 4GL if
you wish to convert CHAR variables with NULL values to empty strings.
To perform arithmetic on numbers stored in variables, use a number data
type. CHAR variables can store digits, but you might not be able to use them
in some calculations. Conversely, leading zeros (in some postal codes, for
example) are stripped from values stored as number data types INTEGER or
SMALLINT. To preserve leading zeros, store such values as CHAR data types.
In most locales, CHAR data types require one byte of storage per character, or
size bytes for size characters. In some East Asian locales, however, more than
one byte may be required to store an individual logical character, and some
white space characters can occupy more than one byte of storage.
By default, when character strings (whether of data type CHAR or VARCHAR)
are sorted by 4GL in a nondefault client locale, collation is in code-set order.
If the COLLATIONsetting in the locale les denes a localizedcollation order,
4GL uses this order to sort CHAR and VARCHAR values, provided that the
DBNLS environment variable is set to 1. (Even if the database locale denes
a nondefault collation sequence, in most contexts the database server uses the
code-set order to sort CHAR and VARCHAR column values.)
GLS
Data Types and Expressi ons 3-17
CHARACTER
The database server generally sorts strings by code-set order, even if the
COLLATION category of the locale denes a nondefault order, except for
values in NCHAR or NVARCHAR columns. (COLLATION functionally
replaces the XPG3 category LC_COLLATE in earlier Informix GLS products.)
If the database and 4GL client have different locales, the order of collation can
depend on whether 4GL or the database server performs the sort operation.
If the database has NCHAR or NVARCHAR columns, you must set the DBNLS
environment variable to 1 if you want to store values from such columns in
CHAR or VARCHAR variables of 4GL, or if you want to insert values of CHAR
or VARCHAR variables into NCHAR or NVARCHAR database columns.
For more information on using non-ASCII values in CHAR columns, see
Appendix E, Developing Applications with Global Language Support.
CHARACTER
The CHARACTER keyword is a synonym for CHAR.
DATE
The DATE data type stores calendar dates. The date value is stored internally
as an integer that evaluates to the count of days since December 31, 1899. The
default display format of a DATE value depends on the locale. In the default
(U.S. English) locale, the default format is
mm/dd/yyyy
where mm is a month (1 to 12), dd is a day of the month (1 to 31 or less), and
yyyy is a year (0001 to 9999). The DBDATE environment variable can change
the separator or the default order of time units for data entry and display.
In some East-Asian locales, the GL_DATE environment variable can specify
Japanese or Taiwanese eras for the entry and display of DATE values. (In any
locale, GL_DATE can specify formats beyond what DBDATE can specify.)
By default, if the user of a 4GL application enters fromthe keyboard a single-
digit or double-digit value for the year, as in 3 or 03, 4GL uses the setting of
the DBCENTURY environment variable to supply the rst two digits of the
year. (Users must pad the year value with one or two leading zeros to specify
years in the First Century; for example, 093 or 0093 for the year 93 A.D.)
GLS
3-18 INFORMIX- 4GL Reference Manual
DATETIME
Dates that are stored as CHAR or VARCHAR strings are not affected by
DBCENTURY; see Appendix D, Environment Variables. You can also set
the CENTURY attribute for individual DATE elds to override the global
DBCENTURY expansion rule in that eld; see CENTURY on page 6-36
for details of setting this eld attribute.
Because DATE values are stored as integers, you can use them in arithmetic
expressions, such as the difference between two DATE values. The result, a
positive or negative INT value, is the number of days that have elapsed
between the two dates. The UNITS DAY operator can convert this to an
INTERVAL data type. (DATE operands in division, multiplication, or
exponentiation operations generally cannot produce meaningful results.)
The FORMAT attribute species DATE display formats in forms. For month,
4GL accepts the value 1 or 01 for January, 2 or 02 for February, and so on. For
days, it accepts a value 1 or 01 for the rst day of the month, 2 or 02 for the
second, and so on, up to the maximum number of days in a given month.
DATETIME
The DATETIME data type stores an instance in time, expressed as a calendar
date and time-of-day. You specify the time units that the DATETIME value
stores; the precision can range from a year through a fraction of a second.
Data values are stored as DECIMAL formats representing a contiguous
sequence of values for units of time.
In some East-Asian locales, the GL_DATETIME environment variable can
specify Japanese or Taiwanese eras for the entry and display of DATETIME
values. (In any locale, however, GL_DATETIME can specify nondefault data
entry and data display formats for DATETIME values.)
DATETIME Qualier
p. 3-76
DATETIME
GLS
Data Types and Expressi ons 3-19
DATETIME
The scale and precision specication is called the DATETIME qualier. It uses
a rst TO last format to declare variables and screen elds. You must
substitute one or two of these keywords for the rst and last terms.
The keyword specifying last in rst TOlast cannot represent a larger unit of
time than rst. Thus, YEARTOSECONDor HOURTOHOUR are valid, but DAY
TO MONTH results in a compiler error, because the value for last (here
MONTH) species a larger unit of time than DAY, the rst keyword.
Unlike INTERVAL qualiers, DATETIME qualiers cannot specify nondefault
precision (except for FRACTION, if that is the last keyword in the qualier).
The following are examples of valid DATETIME qualiers:
B DAY TO MINUTE
B FRACTION TO FRACTION(4)
B YEAR TO MINUTE
B MONTH TO SECOND
Operations with DATETIME values that do not include YEAR in their qualier
use the systemdate to supply any additional precision. If the rst termis DAY
and the current month has fewer than 31 days, unexpected results can occur.
Keyword Corresponding Time Unit and Range of Values
YEAR A year, numbered from 0001 (A.D.) to 9999
MONTH A month, numbered from 1 to 12
DAY A day, numbered from 1 to 31, as appropriate for its month
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 (scale)
or FRACTION
Adecimal fraction of a second, with a scale of up to ve digits;
the default scale is three digits (thousandth of a second)
3-20 INFORMIX- 4GL Reference Manual
DATETIME
For example, assume that it is February, and you wish to store data from
January 31 in the sometime variable that is declared in this statement:
DEFINE sometime DATETIME DAY TO MINUTE
CREATE TABLE mytable (mytime DATETIME DAY TO MINUTE)
LET sometime = DATETIME(31 12:30) DAY TO MINUTE
INSERT INTO mytable VALUES (sometime)
Because the column mytime does not store 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 29. The INSERT statement in this case would fail, because
the value 31 for day is out of range for February. To avoid this problem,
qualify DATETIME data types with YEAR or MONTHas the rst keyword, and
do not enter data values with DAY as the largest time unit.
DATETIME Literals and Delimiters
Statements of 4GL can assign values to DATETIME data types. The simplest
way to do this is as a DATETIME literal or as a character string. Both formats
represent a specic DATETIME value as a numeric DATETIME value.
The DATETIME literal format begins with the DATETIME keyword, followed
by a pair of parentheses that enclose unsigned whole numbers (separated by
delimiters) to represent a consecutive sequence of year through fraction
values, or a subset thereof. This must be followed by a DATETIME qualier,
specifying the rst TO last keywords for the set of time units within the
numeric DATETIME value.
DATETIME Qualier
p. 3-76
DATETIME Literal
p. 3-78
( )
Numeric Date and Time
p. 3-78
DATETIME
Data Types and Expressi ons 3-21
DATETIME
The required delimiters must separate every time unit value in a literal.
DATETIME YEARTOFRACTION(3) values, for example, require six delimiters,
as shown in Figure 3-1.
These are the delimiters that are required for separating successive units of
time within DATETIME literal values.
DATETIME literals can specify every time unit fromthe data type declaration,
or only the units of time that you need. For example, you can assign a value
qualied as MONTH TO HOUR to a variable declared as YEAR TO MINUTE
if the value contains information for a contiguous sequence of time units.
You cannot, however, assign a value for just month and hour; in this case, the
DATETIME literal must also include a value (and delimiters) for day.
A DATETIME literal that species fewer units of time than in the declaration
is automatically expanded to ll all the declared time units. If the omitted
value is for the rst unit of time, or for this andfor other time units larger than
the largest unit that is supplied, the missing units are automatically supplied
from the system clock-calendar. If the value omits any smaller time units,
their values each default to zero (or to 1 for month and day) in the entry. To
specify a year between 1 and 99, you must pad the year value with leading
zeros.
Figure 3-1
Numeric Date
and Time
Delimiter Position Within Numeric DATETIME Value
Hyphen (- ) Between the year, month, and day portions of the value
Blank space Between the day and hour portions
Colon (: ) Between the hour, minute, and second portions
Decimal point (. ) Between the second and fraction portions
98-08-15 12:42:06.011
Fracti on Second Hour Mi nute Month Day Year
Hyphen Space Col on Deci mal poi nt
3-22 INFORMIX- 4GL Reference Manual
DATETIME
The DBCENTURY environment variable determines how single-digit and
double-digit year values are expanded; see Appendix D, Environment
Variables. The CENTURY attribute for an individual DATETIME eld can
override the global DBCENTURY expansion rule within that eld.
Character Strings as DATETIME Values
You can also specify a DATETIME value as a character string, indicating the
numeric values of the date, the time, or both. In a 4GL source module, this
must be enclosed between a pair of quotation ( " ) marks, without the
DATETIME keyword and without qualiers, but with all the required delim-
iters. A pair of single ( ' ) quotation marks is also valid as delimiters. Unlike
DATETIME literals, the character string must include information for all the
units of time declared in the DATETIME qualier. For example, the following
LET statement species a DATETIME value entered as a character string:
LET call_dtime = "1992-08-14 08:45"
In this case, the call_dtime variable was declared as DATETIME YEAR TO
MINUTE, so the character string must specify values for year, month, day,
hour, and minute time units. If the character string does not contain infor-
mation for all the declared time units, an error results. Similarly, an error
results if a delimiter is omitted, or if extraneous blanks appear within the
string.
When a user of the 4GL programenters data in a DATETIME eld of a screen
form, or during a PROMPT statement that expects a DATETIME value, the only
valid format is a numeric DATETIME value, entered as an unquoted string.
Any entry in a DATETIME eld must be a contiguous sequence of values for
units of time and delimiters, in the following format (or in some subset of it):
year-month-day hour:minute:second.fraction
Depending on the data type declaration of the DATETIME eld, each of these
units of time can have values that combine traditional base-10, base-24, base-
60, and lunar calendar values from clocks and calendars.
Values that users enter in a DATETIME eld of the 4GL formneed not include
all the declared time units, but users cannot enter data as DATETIME literals,
a format that is valid only within 4GL statements and in the data type decla-
rations of FORMONLY DATETIME elds of form specication les.
Data Types and Expressi ons 3-23
DEC
DATETIME values are stored internally in the format of xed-point DECIMAL
values (as described in DECIMAL (p, s) on page 3-23), but with sets of
consecutive digits representing the declared time units. All time-unit values
of a DATETIME data type are two-digit numbers, except for the year and
fraction values. The year is stored as four digits. The fraction requires n digits,
for 1 n 5, rounded up to an even number. You can use the following
formula (rounded up to a whole number of bytes) to calculate the number of
bytes required to store a DATETIME value:
( ( total_number_of_digits_for_all_time_units) /2)+1
For example, a YEAR TO DAY qualier requires a total of 8 digits (4 for year,
2 for month, and 2 for day), or ((8/2) + 1) = 5 bytes of storage. For information
about DATETIMEvalues in expressions, see Time Expressions on page 3-72.
DEC
The DEC keyword is a synonym for DECIMAL.
DECIMAL (p, s)
The DECIMAL(p,s) data type stores values as xed-point decimal numbers, of
up to 30 (and for some data values, up to 32) signicant digits. As the syntax
diagram in Simple Data Types on page 3-9 indicates, you can optionally
specify precision (the number of signicant digits) and scale (the number of
digits to the right of the decimal point). For example, DECIMAL (14,2) species
a total of 14 signicant digits, 2 of which describe the fractional part of the
value.
The largest absolute value that a DECIMAL(p,s) data type can store without an
error is 10
p-s
-10
-s
, where p is the precision and s is the scale. Values with an
absolute value less than 0.5 10
-s
are stored as zero. You cannot specify p or
s for a FORMONLY DECIMAL eld in a form; its precision is the smaller of 32
and (length - 2), where length is the eld width in the screen layout.
DECIMAL (p,s) data types are useful for storing numbers with fractional parts
that must be calculated exactly, such as rates or percentages. Unless you are
developing a scientic or engineering application that explicitly controls for
measurement error, store oating-point numbers as DECIMAL(p,s) values.
3-24 INFORMIX- 4GL Reference Manual
DECIMAL (p)
When a user enters data in a SMALLFLOAT or FLOAT eld, 4GL converts the
base-10 value to binary format for storage. Likewise, to display a FLOAT or
SMALLFLOAT number, 4GL reformats it frombinary to base-10. Both conver-
sions can lead to inaccuracy. Thus, if 10.7 is entered into a FLOAT eld, it
might be stored as 10.699999 or as 10.700001, depending on the magnitude
and the sign of the binary-to-decimal conversion error. This limitation is a
feature of digital computers, rather than of 4GL, but it might motivate you to
use DECIMAL(p,s) rather than FLOAT in contexts requiring high precision.
DECIMAL(p,s) values are stored internally with the rst byte representing a
sign bit and a 7-bit exponent in excess-65 format; the rest of the bytes express
the mantissa as base-100 digits. This implies that DECIMAL(32,s) data types
store only s-1 decimal digits to the right of the decimal point, if s is an odd
number. The stored value can have up to 30 signicant decimal digits in its
fractional part, or up to 32 digits to the left of the decimal point. The
following formulae calculate storage (in bytes) needed for DECIMAL(p,s)
values, with any fractional part of the result discarded:
When scale is even: (precision + 3) /2)
When scale is odd: (precision + 4) /2)
For example, DECIMAL(14,2) requires ((14 + 3) / 2), or 8 bytes of storage.
DECIMAL (p)
When you specify both the precision and the scale, the 4GL program can
manipulate the DECIMAL (p,s) value with xed-point arithmetic. If the data
type declaration species no precision or scale, however, the default is
DECIMAL(16), a oating-point number with a precision of 16 digits.
If only one parameter is specied, this is interpreted as the precision of a
oating-point number whose exponent can range from 10
-130
to 10
126
. The
range of absolute data values is approximately from 1.0E-130 to 9.99E+126.
Data Types and Expressi ons 3-25
DOUBLE PRECISION
In an ANSI-compliant database, declaring a column as DECIMAL(p) results in
a xed-point data type with a precision of p and a scale of zero. If you declare
a 4GL data type LIKE a DECIMAL(p) column in an ANSI-compliant Informix
database, the resulting data type is restricted to a scale of zero, which is
equivalent to an integer. For DECIMAL(p,0) data types, any signicant digits
(within the declared precision) in the fractional part of a data value are stored
internally, but are not displayed. For example, if a data value of 0.25 is stored
in the DECIMAL(25,0) variable Q, the value of Qis displayed as zero, but the
Boolean expression (Q > 0) evaluates as TRUE.
DOUBLE PRECISION
The DOUBLE PRECISION keywords are a synonym for FLOAT.
FLOAT
The FLOAT data type stores values as double-precision oating-point binary
numbers with up to 16 signicant digits. FLOAT corresponds to the double
data type in the C language. Values for the FLOAT data type have the same
range of values as the C double data type on your C compiler. FLOAT data
types usually require 8 bytes of memory storage.
For compatibility with the ANSI standard for embedded SQL, you can declare
a whole number between 1 and 14 as the precision of a FLOAT data type, but
the actual precision is data-dependent and compiler-dependent.
A variable of the FLOAT data type typically stores scientic or engineering
data that can be calculated only approximately. Because oating-point
numbers retain only their most signicant digits, a value that is entered into
A FLOAT variable or database column can differ slightly from the numeric
value that a 4GL form or report displays.
This rounding error arises because of the way computers store oating-point
numbers internally. For example, youmight enter a value of 1.1 into a FLOAT
eld. After processing the 4GL statement, the program might display this
value as 1.09999999. This occurs in the typical case where the exact oating-
point binary representation of a base-10 value requires an innite number of
digits in the mantissa. The computer stores a nite number of digits, so it
stores an approximate value, with the least signicant digits treated as zeros.
3-26 INFORMIX- 4GL Reference Manual
INT
Statements of 4GL can specify FLOAT values as oating-point literals.
You can use uppercase or lowercase E as the exponent symbol; omitted signs
default to + (positive). If a number in another format (such as an integer or a
xed-point decimal) is supplied in a .4gl le or from the keyboard when a
FLOAT value is expected, 4GL attempts data type conversion.
In reports and screen displays, the USINGoperator can format FLOAT values.
Otherwise, the default scale in output is two decimal digits.
INT
The INT keyword is a synonym for INTEGER.
INTEGER
The INTEGER data type stores whole numbers in a range from-2,147,483,647
to +2,147,483,647. The negative number -2,147,483,648 is a reservedvalue that
cannot be used. Values are stored as signed 4-byte binary integers, with a
scale of zero, regardless of the word length of your system. INTEGER can
stores counts, quantities, categories coded as natural numbers, and the like.
Arithmetic operations on binary integers are typically without rounding
error; these operations and sort comparisons are performed more efciently
than on FLOAT or DECIMAL data. INTEGER values, however, can only store
data whose absolute value is less than 2
31
. Any fractional part of the value is
discarded. If a value exceeds this numeric range, neither 4GL nor the database
can store the data value as an INTEGER data type.
-1234.56789e-3
Exponent
Manti ssa
Si gn of the manti ssa Si gn of the exponent
Data Types and Expressi ons 3-27
INTERVAL
INTEGER variables can store SERIAL values of the database. If a user inserts a
newrowinto the database, 4GL automatically assigns the next whole number
in sequence to any eldlinkedto a SERIAL column. Users do not needto enter
data into such elds. Once assigned, a SERIAL value cannot be changed. (See
the description of the SERIAL data type in the Informix Guide to SQL: Reference.)
INTERVAL
This data type stores spans of time, the differences between two points in
time. You can also use it to store quantities that are naturally measured in
units of time, such as age or sums of ages, estimated or actual time required
for some activity, or person-hours or person-years of effort attributedto some
task.
An INTERVAL data value is stored as a DECIMAL number that includes a
contiguous sequence of values representing units of time. The INTERVAL
data types of 4GL fall into two classes, based on their declared precision:
B A year-month interval represents a span of years, months, or both.
B A day-time interval represents a span of days, hours, minutes,
seconds, and fractions of a second, or a contiguous subset of those
units.
Automatic data type conversion between these two categories of INTERVAL
data types is not a feature of 4GL.
Unlike DATETIME data types, which they somewhat resemble in their format,
INTERVAL data types can assume zero or negative values. The declaration of
an INTERVAL data type uses the following syntax.
INTERVAL Qualier
p. 3-80
INTERVAL
3-28 INFORMIX- 4GL Reference Manual
INTERVAL
INTERVAL Qualiers
The INTERVAL qualier species the precision and scale of an INTERVAL data
type, using a rst TO last format to declare 4GL variables, formal arguments
of functions and reports, and screen elds. It has the same syntax in declara-
tions of 4GL variables and FORMONLY elds as for INTERVAL columns of the
database. You must substitute one or two keywords from only one the
following lists for rst and last keywords of an INTERVAL qualier.
As with DATETIME data types, you can declare INTERVAL data types to
include only the units that you need. INTERVAL represents a span of time
independent of an actual date, however, so you cannot mix keywords from
both lists in the same INTERVAL qualier. Because the number of days in a
month depends on the month, an INTERVAL data value cannot combine both
months and days as units of time. For example, specifying MONTH TO
MINUTE as an INTERVAL qualier produces a compile-time error.
Arithmetic expressions that combine year-month INTERVAL values with
DATE values (or with DATETIME values that include smaller time units than
month) can return an invalid date, such as February 30. (In general, adding
or subtracting an interval of months from any calendar date later than the
28th day of any month can produce similar errors in SQL and 4GL
expressions.)
For any keyword specifying rst except FRACTION, you have the option of
specifying a precision of up to 9 digits; otherwise the default precision is 2
digits, except for YEAR, which defaults to 4 digits of precision. If an
INTERVAL qualier species only a single unit of time, the keywords speci-
fying rst and last are the same. When rst and last are both FRACTION, you
can only specify the scale after the last keyword.
When last is FRACTION, you can specify a scale of 1 to 5 digits; otherwise, the
scale defaults to 3 digits (thousandth of a second). For example, the following
are valid INTERVAL qualiers:
HOUR TO MINUTE MONTH(5) TO MONTH
FRACTION TO FRACTION(4) HOUR(9) TO FRACTION(5)
Year-Month INTERVAL Keywords Day-Time INTERVAL Keywords
YEAR, MONTH DAY, HOUR, MINUTE, SECOND, FRACTION
Data Types and Expressi ons 3-29
INTERVAL
The keyword specifying the last term cannot represent a larger unit of time
than that specifying rst term. Thus, YEAR TO MONTHand HOUR TO HOUR
are valid, but HOUR TO DAY results in a compiler error, because the rst
keyword (here HOUR) species a smaller unit of time than DAY, the last
keyword.
After you declare an INTERVAL data type, a 4GL statement can assign it the
value of a time expression (as described in Time Expressions on page 3-72)
that species an INTERVAL value. The simplest way to do this is as an
INTERVAL literal or as a character string. Both formats require that you
specify a numeric INTERVAL value.
INTERVAL Literals and Delimiters
The INTERVAL literal format begins with the INTERVAL keyword, followed by
a pair of parentheses that enclose unsigned whole numbers (separated by
delimiters) to represent a consecutive sequence of YEAR through FRACTION
values, or as a portion thereof. This must be followed by a valid INTERVAL
qualier, specifying the rst TO last keywords for the set of time units.
A numeric INTERVAL uses the same delimiters as DATETIME values, except
that month and day need no separator, because they cannot both appear in the
same INTERVAL value. The following delimiters are required for separating
successive units of time within literal INTERVAL values.
Delimiter Position Within Numeric INTERVAL Value
Hyphen (- ) Between the year, month, and day portions of the value
Blank space Between the day and hour portions
Colon (: ) Between the hour, minute, and second portions
Decimal point (. ) Between the second and fraction portions
( )
INTERVAL Qualier
p. 3-80
Numeric Time Interval
p. 3-82
INTERVAL Literal
p. 3-82
INTERVAL
3-30 INFORMIX- 4GL Reference Manual
INTERVAL
Time unit values in a numeric INTERVAL have a default precision of 2 digits,
except for year (4 digits), and fraction (3). The qualier can override these
defaults for the rst time unit, and for the scale of the fraction.
For example, INTERVAL YEAR(3) TO MONTH values require one delimiter.
Similarly, INTERVAL DAY(6) TO FRACTION(2) values require four delimiters.
INTERVAL literals can specify all the time units from the data type decla-
ration, or only the units that you need. For example, you can assign a value
qualied as HOUR TO MINUTE to a variable declared as DAY TO SECOND if
the entered value contains information for a contiguous sequence of time
units. You cannot, however, assign only day and minute values; in this case,
the INTERVAL literal must also include a value (and delimiters) for hour.
The value for the rst time units in an INTERVAL literal can have up to nine
digits of precision (except for FRACTION, which cannot include more than
ve digits). If a rst unit value to be entered is greater than the default
number of digits for that time unit, however, you must explicitly identify the
number of signicant digits that you are entering. For example, an INTERVAL
of DAY TO HOUR that spans 162.5 days can use the following format:
INTERVAL (162 12) DAY(3) TO HOUR
102-08
Month Year
Hyphen
120815 12:42:06.01
Fracti on Second Hour Mi nute Day
Col on Space Deci mal poi nt
Data Types and Expressi ons 3-31
INTERVAL
An INTERVAL literal in a 4GL statement must include numeric values for both
the rst and last time units fromthe qualier, and values for any intervening
time units. You can optionally specify the precision of the rst time unit (and
also a scale, if the last keyword of the INTERVAL qualier is FRACTION).
Character Strings as INTERVAL Values
You can also specify an INTERVAL value as a character string, indicating the
numeric values of the time units. In a 4GL source code module, this must be
enclosed between a pair of quotation ( " ) marks, without the INTERVAL
keyword and without qualiers, but with all the required delimiters. Unlike
INTERVAL literals, the character string must include information for all the
units of time declared in the INTERVAL qualier. For example, the character
string in the next statement species a span of ve years and six months:
LET long_time = "5-06"
Similarly, values entered as character strings into INTERVAL columns of the
database must include information for all time units that were declared for
that column. For example, the following INSERT statement shows an
INTERVAL value entered as a character string:
INSERT into manufact (manu_code, manu_name, lead_time)
VALUES ("BRO", "Ball-Racquet Originals", "160")
Because the lead_time column is dened as INTERVAL DAY(3) TO DAY, this
INTERVAL value requires only one value, indicating the number of days
required. If the character string does not contain information for all the
declared time units, the database server returns an error.
Data Entry by Users
When a user of the 4GL programenters data in an INTERVAL eld of a form,
the only valid format is as an unquoted character string. Any entry into an
INTERVAL eld must be a contiguous sequence of values for units of time
and separators, in one of these two formats (or in some subset of one):
year-month
day hour:minute:second.fraction
3-32 INFORMIX- 4GL Reference Manual
MONEY
Depending on the data type declaration of the eld, each of these units of
time (except the rst) is restricted to values that combine traditional base-10,
base-24, base-60, and lunar calendar values from clocks and calendars.
The rst value can have up to nine digits, unless FRACTION is the rst unit
of time. (If FRACTION is the rst time unit, the maximum scale is 5 digits.)
Values that users enter in an INTERVAL eld of a 4GL form need not include
all the declared time units, but users cannot enter data as INTERVAL literals,
a format that is valid only within 4GL statements and in data type declara-
tions of FORMONLY elds of data type INTERVAL in form specication les.
By default, all values for time units in a numeric INTERVAL are two-digit
numbers, except for the year and fraction values. The year value is stored as
four digits. The fraction value requires n digits where 1 n 5, rounded up
to an even whole number. You can use the following formula (rounded up to
a whole number of bytes) to calculate the number of bytes required for an
INTERVAL value:
( ( total_number_of_digits_for_all_time_units)/2) + 1
For example, a YEAR TO MONTH qualier requires a total of 6 digits (4 for
year and 2 for month), or ((6/2) + 1) = 4 bytes of storage.
For information on using INTERVAL data in arithmetic and relational
operations, see Expressions of 4GL on page 3-49.
MONEY
The MONEYdata type stores currency amounts. Like the DECIMAL data type,
the MONEY data type stores xed-point numbers, up to a maximum of 32
signicant digits. As the syntax diagramin Simple Data Types on page 3-9
indicates, you can optionally include one or two whole numbers to specify
the precision (the number of signicant digits) and the scale (the number of
digits to the right of the decimal point).
Unlike the DECIMAL data type (described in DECIMAL (p, s) on
page 3-23), which stores oating-point numbers if its data type declaration
species neither scale nor precision, MONEY values are always stored as
xed-point decimal numbers. If you declare a MONEY data type with only
one parameter, 4GL interprets that parameter as the precision. By default, the
scale is 2, so the data type MONEY(p) is stored internally as DECIMAL(p,2),
where p is the precision (1 p 32).
Data Types and Expressi ons 3-33
NUMERIC
If no parameters are specied, MONEY is interpreted as DECIMAL(16,2). This
stores 16 signicant digits, 2 of which describe the fractional part of the
currency value. The largest absolute value that you can store without error as
a MONEY data type is 10
p-s
-10
-s
. Here p is the precision, and s is the scale.
Values with an absolute value less than 0.5 x 10
-s
are stored as zero. You
cannot specify the precision or the scale of a FORMONLY MONEY eld in a
4GL form; here the precision defaults to the smaller of 32 or (length - 2), where
length is the eld length from the SCREEN section layout.
On the screen, MONEY values are displayed with a currency symbol, by
default, a dollar sign ( $ ), and a decimal point ( . ) symbol. You can change
the display format for MONEY values in the DBMONEY or DBFORMAT
environment variable. The settings of these variables take precedence over
the default currency format of the locale. 4GL statements and keyboard input
by users to elds of screen forms do not need to include currency symbols in
literal MONEY values.
The same formulae as for DECIMAL values apply to MONEY data types, with
any fractional part of the result discarded:
When scale is even: (precision + 3) /2
When scale is odd: (precision + 4) /2
For example, a MONEY(13,2) variable has a precision of 13 and a scale of 2.
This requires ((13 + 3) /2) = 8 bytes of storage.
NUMERIC
The NUMERICkeyword is a synonymfor DECIMAL. (When the word numeric
appears in lowercase letters in this manual, it is always the adjective formed
from the noun number, rather than the name of a data type.)
REAL
The REAL keyword is a synonym for SMALLFLOAT. (When the phrase real
number appears in lowercase letters in this manual, it denotes a number that
is neither imaginary nor transnite, rather than the name of a data type.)
3-34 INFORMIX- 4GL Reference Manual
RECORD
RECORD
The RECORD data type is an ordered set of variables. Within each of these
sets (called a program record), the component variables (called members) can
be of any 4GL data type, or any combination of data types in a xed order.
Valid data types for member variables of records include all the simple data
types (listed in Simple Data Types on page 3-9), the large data types (BYTE,
TEXT), and the structured data types (ARRAY, RECORD). The following is the
data type declaration syntax for RECORD variables.
You can use the LIKE keyword to specify that a member variable has the same
data type as a database column. If you do not specify member names, but use
an asterisk ( * ) after a table name, you declare a record whose members have
the same identiers as the columns in table; their data types correspond to the
xed sequence of SQL data types in an entire row of the table. (Any SERIAL
column in table corresponds to a record member of data type INTEGER.)
Element Description
column is the name of a column in the default (or specied) database.
member is a name that you declare for a member variable of the record.
table is the SQL identier of a database table, synonym, or view.
Simple Data Type
p. 3-9
member END RECORD
,
RECORD
table.* LIKE
LIKE
RECORD Data
Type
column
Table Qualier
p. 3-90
Table Qualier
p. 3-90
table.
Data Types and Expressi ons 3-35
RECORD
This example uses the LIKE keyword to declare two programrecords, one of
which contains a member variable called nested of the RECORD data type:
DEFINE p_customer RECORD LIKE informix.customer.*,
p_orders RECORD
order_num LIKE informix.orders.order_num,
nested RECORD a LIKE informix.items.item_num,
b LIKE informix.stock.unit_descr
END RECORD
END RECORD
If table is a view, the column cannot be based on an aggregate. You cannot
specify table.* if table is a view that contains an aggregate column.
In an ANSI-compliant database, you must qualify the table name with the
owner prex, if the programwill be run by users other than owner. If the table
is an external or external, distributed table, its name must be qualied by the
name of the remote database and by the name of its database server.
If the client locale and the database locale are not identical, do not use
the LIKE keyword to declare a member variable whose name is the same
as a database column whose identier includes any non-ASCII character that
is not supported by the character set of the client locale.
Referencing Record Members
If record is the identier that you declare for a program record in a DEFINE
statement, or the name of a screen record in a 4GL form, you can use the
following notation to reference members of the record in 4GL statements:
B The notation record.member refers to an individual member of a
record, where member is the identier of the member.
B The notation record.rst THRU record.last refers to a consecutive
subset of members, fromrecord.rst through record.last. Here rst is
an identier that was listed before last among the explicit or implicit
member names in the RECORD declaration. You can also use the
keyword THROUGH as a synonym for THRU.
B The notation record.* refers to the entire record.
GLS
3-36 INFORMIX- 4GL Reference Manual
SMALLFLOAT
Several restrictions apply when you reference members of a record:
B You cannot use THRUor THROUGHto indicate a partial list of screen
record members in 4GL statements for displaying or entering data in
a screen form.
B You cannot use THRU, THROUGH, or .* to reference a programrecord
that contains an ARRAY variable among its members. (But you can
use these notations to specify all or part of a record that contains one
or more other records as members.)
B You cannot use THRU, THROUGH, or .* notation in a SELECT or
INSERT variable list in a quoted string in PREPARE statements. (You
can, however, use the .* notation to specify a program record in the
variable list of an INSERT or SELECT clause of a DECLARE statement.)
A program record whose members correspond in number, order, and data
type compatibility to a database table or to a screen record can be useful for
transferring data from the database to the screen, to reports, or to functions
of the 4GL program. For more information, see Summary of Compatible 4GL
Data Types on page 3-45 and Chapter 7, INFORMIX-4GL Reports.
SMALLFLOAT
The SMALLFLOAT data type stores single-precision oating-point binary
numbers, with up to 8 signicant digits. The range of values is the same
as for the oat data type of C. The storage requirement is usually 4 bytes.
The SMALLFLOAT data type typically stores scientic or engineering data
that can only be calculated approximately. Because oating-point numbers
retain only their most signicant digits, a value entered into a SMALLFLOAT
variable or column can differ slightly fromthe base-10 value that an 4GL form
or 4GL report displays.
This error arises from the internal storage format of binary oating-point
numbers. For example, if you enter a value of 1.1 into a SMALLFLOAT eld,
after processing the 4GL statement, the screen might display this value as
1.1000001. This occurs in the typical case where the exact oating-point
binary representation of a base-10 value requires an innite number of digits
in the mantissa. Acomputer stores only a nite number of digits, so it stores
an approximate value, with the least-signicant digits treated as zeros.
Data Types and Expressi ons 3-37
SMALLINT
Statements of 4GL can specify SMALLFLOAT values as oating-point literals,
using the following format.
You can use uppercase or lowercase E as the exponent symbol; omitted signs
default to + (positive). If a literal value in another format (such as an integer
or a xed-point decimal) is supplied fromthe keyboard into a SMALLFLOAT
eld, or in a 4GL statement, 4GL attempts data type conversion.
In reports and screen displays, the USING operator can format SMALLFLOAT
values. The default scale in output, however, is two digits.
SMALLINT
The SMALLINT data type stores data as signed 2-byte binary integers. Values
must be whole numbers within the range from -32,767 to +32,767. Any
fractional part of the data value is discarded. If a value lies outside this range,
youcannot store it ina SMALLINT variable or database column. (The negative
value -32,768 is reserved; it cannot be assigned to a SMALLINT variable or
database column, and it cannot be entered into a SMALLINT eld of a form.)
You can use SMALLINT variables and FORMONLY elds of screen forms
to store, manipulate, and display data that can be represented as whole
numbers of an absolute value less than 2
15
. This data type typically stores
small whole numbers, Boolean values, ranks, or measurements that classify
data into a small number of numerically-coded categories. Because the
SMALLINT data type requires only 2 bytes of storage, arithmetic operations
on SMALLINT operands can be done very efciently, provided that all of the
data values lie within the somewhat limited SMALLINT range.
-1234.5e-3
Exponent
Si gn of the exponent Si gn of the manti ssa
Manti ssa
3-38 INFORMIX- 4GL Reference Manual
TEXT
TEXT
The TEXT data type stores character data in ASCII strings. TEXT resembles the
BYTE data type, but 4GL supports features to display TEXT variables whose
values are restricted to combinations of printable ASCII characters and the
following white space characters:
B TAB (= CONTROL-I)
B NEWLINE (= CONTROL-J)
B FORMFEED (= CONTROL-L)
If you attempt to include other non-printable characters in TEXT values, the
features of 4GL for processing TEXT data might not work correctly.
In some locales, other white space characters are supported; more than one
byte is required to store some East-Asian white space characters.
Strings stored as TEXT variables have a theoretical limit of 2
31
bytes, and a
practical limit determined by the available storage on your system.
INFORMIX-SE database servers do not support TEXT columns, but regardless
of the database server, you can declare 4GL variables of type TEXT.
You can use a TEXT variable to store, retrieve, or update the contents of a
TEXT database column, or to reference a le that you wish to display to users
of the 4GL programthrough a text editor. After you declare a TEXT data type,
you must use the LOCATE statement to specify the storage location.
When you retrieve a value froma TEXT column, you can assign all or part of
it to a TEXT variable. Use brackets ( [ ] ) and comma-separated subscripts to
reference only a specied part of a TEXT value, as in the following example:
SELECT cat_description [1,75] INTO cat_nap FROM catalog
WHERE catalog_num = 10001
This reads the rst 75 bytes of the cat_description column of the rowwith the
catalog number 10001, and stores these data in the cat_nap TEXT variable.
GLS
SE
Data Types and Expressi ons 3-39
VARCHAR
Restrictions on TEXT Variables
In a 4GL form, a eld linked to a TEXT column (or a FORMONLY eld of type
TEXT) only displays as many characters as can t in the eld. To display TEXT
values longer than the screen eld, or to edit a TEXT value, you must assign
the PROGRAM attribute to the TEXT eld. The WORDWRAP attribute can
display the initial characters of a TEXT value, up to the last segment of the
eld, but cannot edit a TEXT eld. No other 4GL eld attribute (except
COLOR) can reference the value of a TEXT eld.
In a CALL, OUTPUT TO REPORT, or RETURN statement, TEXT arguments are
passed by reference, rather than by value. (Passing Arguments by
Reference on page 4-18 discusses this issue in greater detail.) The DISPLAY
TOstatement can display a TEXT value, but DISPLAY and DISPLAY AT cannot.
The LET statement cannot assign any value (except NULL) to a TEXT variable.
Built-in functions of 4GL cannot specify TEXT arguments. Expressions of 4GL
(as described in Expressions of 4GL on page 3-49) can reference TEXT
variables only to test for NULL values, or as an operand of WORDWRAP.
VARCHAR
The VARCHAR data type stores character strings of varying lengths. You can
optionally specify the maximum size of a data string, and the minimum
storage reserved on disk.
INFORMIX-SE database servers do not support this data type, but any 4GL
application can declare VARCHAR variables.
The declared size of VARCHAR can range from 1 to 255 bytes. If you specify
no size, the default is 1. The data type can store shorter character strings than
this maximum size, but not longer strings. In a form specication le, you
cannot specify any parameters for a FORMONLY VARCHAR eld; here the size
defaults to the physical eld length in the screen layout.
In data type declarations, the minimumreserved storage can range from0 to
255 bytes, but this cannot be greater than the declared size. Just as 4GL accepts
but ignores the precision specication in FLOAT or DOUBLE PRECISION data
type declarations for compatibility with ANSI/ISO SQL syntax, 4GL accepts
but ignores reserved in VARCHAR declarations. (But in SQL declarations like
CREATE TABLE, the reserved value can affect the behavior of the database.)
SE
3-40 INFORMIX- 4GL Reference Manual
VARCHAR
The ASCII 0 end-of-data character terminates every VARCHAR value; any
subsequent characters in a data string generally cannot be retrieved fromor
entered into VARCHAR (nor CHAR) database columns.
When you assign a value to a VARCHARvariable, only the data characters are
stored, but neither 4GL nor the database server strips a VARCHAR value of
user-entered trailing blanks. Unlike CHAR values, VARCHAR values are not
padded with blank spaces to the declared maximum size, so the CLIPPED
operator may not be needed in operations on VARCHAR values.
VARCHAR values are compared to CHAR values and to other VARCHAR
values in 4GL Boolean expressions in the same way that CHAR values are
compared: the shorter value is padded on the right with spaces until both
values have equal lengths and they are compared for the full length.
In most locales, VARCHAR values require one byte of storage per character,
or size bytes for size characters. In some East Asian locales, however, more
than one byte may be required to store an individual logical character, and
some white space characters can occupy more than one byte of storage.
If a collation order is dened by the COLLATIONcategory in a locale le, the
database server uses this order to sort values fromNVARCHAR and NCHAR
database columns in SQL statements, but uses code-set order to sort CHAR or
VARCHAR values. If DBNLS is set to 1, 4GL uses COLLATIONto sort CHAR or
VARCHAR variables; otherwise, 4GL uses code-set order. If 4GL and the
database have different locales, collation order for a sorting operation might
depend on whether 4GL or the database server performs the sort.
If the database has NVARCHAR or NCHAR columns, you must set the DBNLS
environment variable to 1 if you want to store values from such columns in
VARCHAR or CHAR variables of 4GL, or if you want to insert values of CHAR
or VARCHAR variables into NCHAR or NVARCHAR database columns.
For more information, see Appendix E, Developing Applications with
Global Language Support.
GLS
Data Types and Expressi ons 3-41
Data Type Conversi on
Data Type Conversion
4GL can assign the value of a number, character string, or point in time to a
variable of a different data type. 4GL performs data type conversion without
objection when the process makes sense. If you assign a number expression
to a CHAR variable, for example, 4GL converts the resulting number to a
literal string. In an expression, 4GL attempts to convert the string represen-
tation of a number or time value to a number, time span, or point in time.
An error is issued only if 4GL cannot perform the conversion. For example,
4GL converts the string "123.456" to the number 123.456 in an arithmetic
expression, but adding the string "Juan" to a number produces an error.
The global status variable is not reset when a conversion error occurs, unless
you specify the ANY ERROR keywords (without CONTINUE) in a WHENEVER
compiler directive, or include the - anyerr command-line argument.
Converting from Number to Number
When you pass a value fromone number data type to another, the receiving
data type must be able to store all of the source value. For example, if you
assign an INTEGER value to a SMALLINT variable, the conversion will fail if
the absolute value is larger than 32,767. Overow can also occur when you
transfer data fromFLOAT or SMALLFLOAT variables or database columns to
INTEGER, SMALLINT, or DECIMAL data types.
The kinds of errors that you might encounter when you convert values from
one number data type to another are listedin Notes on Automatic Data Type
Conversion on page 3-47. For example, if you convert a FLOAT value to
DECIMAL(4,2), 4GL or the database server rounds off the oating-point value
before storing it as a xed-point number. This can sometimes result in
overow, underow, or rounding errors, depending on the data value andon
the declared precision of the receiving DECIMAL data type.
The SQLAWARN[1] and SQLAWARN[5] characters of the global SQLCA
record are set to W after any FLOAT or SMALLFLOAT value is converted
to a DECIMAL value.
3-42 INFORMIX- 4GL Reference Manual
Data Type Conversi on
Converting Numbers in Arithmetic Operations
4GL performs most arithmetic operations on DECIMAL values, regardless of
the declared data types of the operands. (The exceptions are integers; see
Arithmetic Operators on page 3-66.) The data type of the receiving variable
determines the format of the stored or displayed result.
The following rules apply to the precision and scale of the DECIMAL variable
that results from an arithmetic operation on two numbers:
B All operands, if not already DECIMAL, are converted to DECIMAL,
and the result of the arithmetic operation is always a DECIMAL.
B In addition and subtraction, 4GL adds trailing zeros to the operand
with the smaller scale, until the scales are equal.
B If the data type of the result of an arithmetic operation requires the
loss of signicant digits, 4GL reports an error.
B Leading or trailing zeros are not considered signicant digits, and do
not contribute to the determination of precision and scale.
B If one operand has no scale (that is, a oating-point decimal), the
result is also a oating-point decimal.
B The precision and scale of the result of an arithmetic operation
depend on the precision and scale of the operands and on the arith-
metic operator. The rules of 4GL are summarized in the following
table for arithmetic operands that have a denite scale.
Source Operand Converted Operand
FLOAT DECIMAL (16)
INTEGER DECIMAL (10, 0)
MONEY (p) DECIMAL (p, 2)
SMALLFLOAT DECIMAL (8)
SMALLINT DECIMAL (5, 0)
Data Types and Expressi ons 3-43
Data Type Conversi on
In this table, p
1
and s
1
represent the precision and scale of the rst operand,
and p
2
and s
2
represent the precision and scale of the second operand.
These values are upper limits, because the actual precision and scale of
DECIMAL(p,s) values are data-dependent. The USING operator can override
the default scale when output is displayed.
Converting Between DATE and DATETIME
You can convert DATE values to DATETIME values. If the DATETIME precision
includes time units smaller than day, however, 4GL either ignores the time-of-
day units or else lls them with zeros, depending on the context. The
examples that follow illustrate how these two data types are converted; it is
assumed here that the default display format for DATE values is mm/dd/yyyy:
B If a DATE value is specied where a DATETIME YEAR TO DAY is
expected, 4GL converts the DATE value to a DATETIME value. For
example, 08/15/1999 becomes 1999-08-15.
B If a DATETIME YEAR TO DAY value is specied where a DATE is
expected, 1999-08-15 becomes 08/15/1999.
B If a DATE value is specied where a DATETIME YEAR TO FRACTION
(or TOSECOND, TOMINUTE, or TOHOUR) is expected, 4GL converts
the DATE value to a DATETIME value, and lls any smaller time units
from the DATETIME declaration with zeros. For example, the DATE
value 08/15/1999 becomes 1999-08-15 00:00:00.
B If a DATETIME YEAR TOSECONDto DATE, value is specied where a
DATE is expected, 4GL converts the DATETIME value to a DATE value,
but drops any time units smaller than DAY. Thus, 1999-08-15
12:31:37 becomes 08/15/1999.
Numeric Operation Precision and Scale of Returned Value
Addition ( + ) and
Subtraction ( - )
Precision: MIN(32, MAX(p
1
- s
1
, p
2
- s
2
) + MAX(s
1
, s
2
) + 1)
Scale: MIN( 30, MAX(s
1
, s
2
) )
Multiplication ( * ) Precision: MIN(32, p
1
+ p
2
)
Scale: MIN(30, s
1
+ s
2
)
Division ( / ) Precision: 32
Scale: MAX(0, 32 - p
1
+ s
1
- s
2
)
3-44 INFORMIX- 4GL Reference Manual
Data Type Conversi on
The EXTEND( ) operator can return a DATETIME value froma DATE operand.
Converting CHAR to DATETIME or INTERVAL Data Types
You can specify DATETIME and INTERVAL data in literal formats, as
described in previous sections, or as quoted strings. Values specied as
suitably formatted character strings are automatically converted into
DATETIME or INTERVAL values, if the string species a value for every time
unit declared for that DATETIME or INTERVAL variable. The next examples
illustrate both formats for December 5, 1974, and for a time interval of nearly
18 days:
DEFINE mytime DATETIME YEAR TO DAY,
myval INTERVAL DAY TO SECOND
LET mytime = DATETIME(74-12-5) YEAR TO DAY
LET mytime = "74-12-5" --same effect as previous line
LET myval = INTERVAL(17 21:15:30) DAY TO SECOND
LET myval = "17 21:15:30" --same effect as previous line
When a character string is converted into a DATETIME or INTERVAL value,
4GL assumes that the character string includes information about all the
declared time units. You cannot use character strings to enter DATETIME or
INTERVAL values for a subset of time units, because this produces
ambiguous values. If the character string does not contain information for all
the declared time units, 4GL returns an error, as in some of these examples:
DEFINE tyme DATETIME YEAR TO DAY,
mynt INTERVAL DAY TO SECOND
LET tyme = DATETIME(5-12) MONTH TO DAY --Valid
LET tyme = "5-12" --Error!
LET mynt = INTERVAL(11:15) HOUR TO MINUTE --Valid
LET mynt = "11:15" --Error!
The previous DATETIME example (variable tyme) assigns a MONTH TO DAY
value to a variable declared as YEAR TO DAY. Entering only these values is
valid in the rst LET statement because the qualier of the DATETIME literal
species no year, so 4GL automatically supplies the value of the current year.
In the example of the character string, however, 4GL does not knowwhether
the "5-12" refers to year and month, or month and day, so it returns an error.
Data Types and Expressi ons 3-45
Summary of Compati bl e 4GL Data Types
The previous INTERVAL example (variable mynt) assigns an HOUR TO
MINUTE value to a variable declared as DAY TO SECOND. The rst LET
statement simply pads the value with zeros for day and second. The second
LET statement produces a conversion error, however, because 4GL does not
knowwhether "11:15" species HOUR TOMINUTE or MINUTE TOSECOND.
Empty or blank strings are converted to null time (or number) values.
Converting Between Number and Character Data Types
You can store a CHAR or VARCHAR value in a number variable and vice
versa. But if the CHAR or VARCHAR value contains any characters that are
not valid in a number data type (for example, the letters l or O instead of the
digits 1 or 0), 4GL returns a data type conversion error.
In a locale that is not U.S. English, if number or currency values are converted
to character strings during the LET statement, the conversion process inserts
locale-specic separators and currency symbols into the converted strings,
rather than the default U.S. English separators and currency symbols.
Converting Large Data Types
You can store a TEXT value in a BYTE data type. No other data type conver-
sions involving large binary data types are supported directly by 4GL.
Summary of Compatible 4GL Data Types
Some ordered pairs of 4GL data types are said to be compatible, in the sense
that automatic data type conversion is possible for some non-null data
values. As Notes on Automatic Data Type Conversion on page 3-47
indicates, however, whether conversionoccurs without error is inmany cases
data-dependent, and is typically sensitive to the declared length, precision,
or scale of the receiving data type.
The table that follows shows which pairs of 4GL data types are compatible.
3-46 INFORMIX- 4GL Reference Manual
Summary of Compati bl e 4GL Data Types
These relationships apply to values of simple data types, to simple members
of RECORD data types, and to simple elements of ARRAY data types:
B Unshaded cells show the types of values (listed in the top row) that
4GL can assign to each type of variable (listed on the left).
B Shaded cells indicate incompatible pairs of data types, for which 4GL
does not support automatic data type conversion.
Data Type of Value to Be Passed
C
H
A
R
V
A
R
C
H
A
R
I
N
T
E
G
E
R
S
M
A
L
L
I
N
T
F
L
O
A
T
S
M
A
L
L
F
L
O
A
T
D
E
C
I
M
A
L
M
O
N
E
Y
D
A
T
E
D
A
T
E
T
I
M
E
I
N
T
E
R
V
A
L
R
e
c
e
i
v
i
n
g

D
a
t
a

T
y
p
e
CHAR
' ' ' ' ' ' ' '0 'O ' '
VARCHAR
' ' ' ' ' ' ' '0 'O ' '
INTEGER
^ ^ O
SMALLINT
^ ^ O
FLOAT
^I ^I O O O
SMALLFLOAT
^I ^I OI O I I I OI
DECIMAL
^I ^I I I I I O
MONEY
^I ^I I I I I O
DATE
^ ^ O O O O O O O6
DATETIME
^ ^ O6 I6
INTERVAL
^ ^ I
Data Types and Expressi ons 3-47
Summary of Compati bl e 4GL Data Types
Symbols in the cells refer to notes in the next section. These apply when the
data types of the passed value and of the receiving variable are not identical:
B Light circles ( ') indicate the possibility of conversion failure, or
discrepancies between the passed value and the receiving data type.
B Dark circles ( 0) indicate features that usually do not cause
conversion errors, but can produce unexpected data formats or
values.
Notes on Automatic Data Type Conversion
In the previous table, numbers within light circles ( ') indicate restrictions
that can cause the data type conversion to fail, or that can sometimes result
in discrepancies between the passed value and the receiving variable.
' If the result of converting a value to a character string is longer than the
receiving variable, the character string is truncated from the right.
^ Character string values must depict a literal of the receiving data type.
If the value exceeds the range of the receiving data type, an overow
error occurs.
Any fractional part of the value is truncated.
I If the passed value contains more signicant digits than the receiving
data type supports, low-order digits are discarded.
I If the passed value contains more fractional digits than the receiving
data type supports, low-order digits are discarded.
I Differences in qualiers can cause truncation from the left or right.
3-48 INFORMIX- 4GL Reference Manual
Summary of Compati bl e 4GL Data Types
Numbers in dark circles ( 0) indicate less critical conversion features. These
can result in the assignment of unexpected values, or unexpected formats.
You may wish to avoid writing code that applies automatic conversion to
DATETIME variables declared with time units smaller than YEAR as the rst
keyword of the qualier unless default values that feature ( 6) assigns from
the system clock are useful in your application. For more information, see
Chapter 2, The INFORMIX-4GL Language.
0 DBMONEY or DBFORMAT controls the format of the converted string.
O DBFORMAT, DBDATE, or GL_DATE controls the format of the result.
O Rounding errors can produce an assigned value with a fractional part.
O An integer value corresponding to a count of days is assigned.
O An implicit EXTEND (value, YEAR TO DAY) is performed by 4GL.
O The DATE becomes a DATETIME YEAR TODAY literal before assignment.
6 If the passed value has less precision than the receiving variable, any
missing time unit values are obtained from the system clock.
Data Types and Expressi ons 3-49
Expressi ons of 4GL
Expressions of 4GL
A 4GL expression is a sequence of operands, operators, and parentheses that
4GL can evaluate as a single value.
Usage
Statements, functions, form specications, operators, and expressions can
have expressions as arguments, components, or operands. The context where
an expression appears, as well as its syntax, determines the data type of its
returned value. It is convenient to classify 4GL expressions into the following
ve categories, based on the data type of the value that they return.
Expression Type What the Expression Returns
Boolean A value that is either TRUE or FALSE (or null in some contexts)
Integer A whole-number value of data type INT or SMALLINT
(1 of 2)
4GL
Expression
DATETIME
Expression
p. 3-74
INTERVAL
Expression
p. 3-74
DATE
Expression
p. 3-74
Time Expressions:
Character Expression
p. 3-68
Number Expression
p. 3-66
Integer Expression
p. 3-63
Boolean Expression
p. 3-60
4GL
Expression
Number Expressions:
( )
3-50 INFORMIX- 4GL Reference Manual
Di fferences Between 4GL and SQL Expressi ons
In this manual, if the term4GL expression is not qualied as one of these ve
data type categories, the expression can be any 4GL data type.
As the diagramsuggests, 4GL Boolean expressions are special cases of integer
expressions, which in turn are a logical subset of number expressions.
You can substitute a 4GL Boolean or integer expression where a number
expression is valid (unless this results in an attempt to divide by zero).Topics
that are discussed in this section include the following:
B Components of 4GL Expressions on page 3-52
B Boolean Expressions on page 3-60
B Integer Expressions on page 3-63
B Number Expressions on page 3-66
B Character Expressions on page 3-68
B Time Expressions on page 3-72
Differences Between 4GL and SQL Expressions
Expressions in SQL statements (and in SPL statements) are evaluated by the
database server, not 4GL. The set of operators that can appear in SQL or SPL
expressions resembles the set of 4GL operators, but they are not identical.
Number A value of any of the Number Data Types (page 3-10).
Character A character string of data type CHAR or VARCHAR
Time A value of data type DATE, DATETIME, or INTERVAL
Expression Type What the Expression Returns
(2 of 2)
Data Types and Expressi ons 3-51
Di fferences Between 4GL and SQL Expressi ons
A 4GL program can include SQL operators, but these are restricted to SQL
statements. Similarly, most SQL (and all SPL) operands are not valid in 4GL
expressions. The SQL identiers of databases, tables, or columns can appear
in a LIKE clause or eld name in 4GL statements (as described in Field
Clause on page 3-87), provided that these SQL identiers comply with the
naming rules of 4GL, but the following SQL and SPL operands and operators
cannot appear in other 4GL expressions:
B SQL identiers, such as column names
B The names of SPL variables
B The SQL keywords USER and ROWID
B Built-in or aggregate SQL functions that are not part of 4GL
B The BETWEEN and IN operators (except in form specications)
B The EXISTS, ALL, ANY, or SOME keywords of SQL expressions
Conversely, you cannot include the following 4GL operators in SQL or SPL
expressions:
B Arithmetic operators for exponentiation ( ** ) and modulus (MOD)
B String operators ASCII, COLUMN, SPACE, SPACES, and WORDWRAP
B Field operators FIELD_TOUCHED( ), GET_FLDBUF( ), and INFIELD( )
B The report operators LINENO and PAGENO
B The time operators DATE( ) and TIME
These and other built-in functions and operators of 4GL are described in
Chapter 5, Built-In Functions and Operators.
See the Informix Guide to SQL: Syntax for the syntax of SQL expressions and
SPL expressions.
3-52 INFORMIX- 4GL Reference Manual
Components of 4GL Expressi ons
Components of 4GL Expressions
An expression of 4GL can include the following components:
B Operators, as listed on the next page
B Parentheses, to override the default precedence of operators
B Operands, including the following:
O Named values
O Function calls returning a single value
O Field names
O Literal values
O Other 4GL expressions
Parentheses in 4GL Expressions
You can use parentheses as you would in algebra to override the default
order of precedence of 4GL operators. In mathematics, this use of parentheses
represents the associative operator. It is, however, a convention in
computer languages to regard this use of parentheses as delimiters rather
than as operators. (Do not confuse this use of parentheses to specify operator
precedence with the use of parentheses to enclose arguments in function calls
or to delimit other lists.)
In the following example, the variable y is assigned the value of 2:
LET y = 15 MOD 3 + 2
In the next example, however, y is assigned the value of 0 because the paren-
theses change the sequence of operations:
LET y = 15 MOD (3 + 2)
Chapter 4, INFORMIX-4GL Statements, describes the LET statement of
4GL, which can assign the value of an expression to a variable of a compatible
data type.
Data Types and Expressi ons 3-53
Components of 4GL Expressi ons
Operators in 4GL Expressions
The operators listedinFigure 3-2 onpage 3-54 canappear in4GL expressions.
Expressions with several operators are evaluated according to their prece-
dence, from highest (16) to lowest (1), as indicated in the left-most (P)
column. In the previous example, although the modulus operator (MOD) had
a higher precedence than the addition ( + ) operator, the parentheses
instructed 4GL to perform the addition rst, contrary to the default order of
operator precedence.
The P values that indicate precedence in Figure 3-2 are ordinal numbers; they
may change if future releases add new operators.
The fourth column (A) indicates the direction of associativity, if any, of each
operator.ws See the page references in the right-most column of Figure 3-3 on
page 3-55 for additional information about individual operators of 4GL.
3-54 INFORMIX- 4GL Reference Manual
Components of 4GL Expressi ons
Figure 3-2
Precedence ( P ) and Associativity ( A ) of 4GL Operators
P Operator Description A Example Page
16 . Record membership Left myrec.memb 3-34
[ ] Array index or substring Left ar[i,6,k][2,(int-expr)] 3-13
( ) Function call None myfun(var1,expr) 3-58
15 UNITS Single-qualier interval Left (int-expr) UNITS DAY 5-26
14 + Unary plus Right + (number-expr) 3-65
- Unary minus Right - numbarray_var3[i,j,k] 3-65
13 * * Exponentiation (by integer) Left (number-expr) ** (int-expr) 3-64
MOD Modulus (of integer) Left (int-expr) MOD (int-expr) 3-64
12 * Multiplication Left x * (number-expr) 3-64
/ Division Left (number-expr) / arr[y] 3-64
11 + Addition Left (number-expr) + (number-expr) 3-64
- Subtraction Left (x - y) - (number-expr) 3-64
10 || Concatenation Left "str" || "ing" 5-49
9 LIKE String comparison Right (character-expr) LIKE "%z_%" 5-37
MATCHES String comparison Right (character-expr)MATCHES"*z?" 5-37
8 < Test for: less than Left (expr1) < (expr2) 5-35
<= Less than or equal to Left x <= yourfun(y,z) 5-35
= or == Equal to Left x = expr 5-35
>= Greater than or equal to Left x >= FALSE 5-35
> Greater than Left var1 > expr 5-35
!= or <> Not equal to Left myrec.memb<>LENGTH(var1) 5-35
7 IN( ) Test for: set membership Right expr1 NOT IN (x,3,expr2) 5-40
6 BETWEEN ... AND Test for: range Left BETWEEN (integer-expr) AND 9 5-40
5 IS NULL Test for: NULL Left x IS NULL OR y IS NOT NULL 5-36
4 NOT Logical inverse Left NOT ((expr) IN (y,DATE)) 3-61
3 AND Logical intersection Left expr1 AND fun(expr2,-y) 3-61
2 OR Logical union Left LENGTH(expr1,j) OR expr2 3-61
1 ASCII Return ASCII character Right LET x = ASCII (int-expr) 5-31
CLIPPED Delete trailing blanks Right DISPLAY poodle CLIPPED 5-44
COLUMN Begin line-mode display Right PRINT COLUMN 58, "30" 5-46
ORD Logical inverse of ASCII Right LET key = ORD(character-expr) 5-94
SPACES Insert blank spaces Right DISPLAY (int-expr) SPACES 5-102
USING Format character string Right TODAY USING "yy/mm/dd" 5-115
WORDWRAP Multiple-line text display Right PRINT odyssey WORDWRAP 5-128
Data Types and Expressi ons 3-55
Components of 4GL Expressi ons
Figure 3-3
Data Types of Operands and of Returned Values
P Expression Left (= x) Right (= y) Returned Value Page
16 x . y RECORD Any Same as y 5-91
w [x , y] INT or SMALLINT INT or SMALLINT Any or Character 5-106
( y ) Any or Large Any 3-58
15 x UNITS INT or SMALLINT INTERVAL 5-111
14 + y Number or INTERVAL Same as y 5-22
- y Number or INTERVAL Same as y 5-22
13 x * * y Number INT or SMALLINT Number 5-25
x MOD y INT or SMALLINT INT or SMALLINT INT or SMALLINT 5-25
12 x * y Number or INTERVAL Number Number or INTERVAL 5-25
x / y Number or INTERVAL Number Number or INTERVAL 5-25
11 x + y Number or Time Number or Time Number or Time 5-26
x - y Number or Time Number or Time Number or Time 5-26
10 x || y Any Any Character 5-49
9 x LIKE y Character Character Boolean 5-37
x MATCHES y Character Character Boolean 5-37
8 x < y Any Same as x Boolean 5-34
x <= y Any Same as x Boolean 5-34
x = y or x == y Any Same as x Boolean 5-34
x >= y Any Same as x Boolean 5-34
x > y Any Same as x Boolean 5-34
x != y or x <> y Any Same as x Boolean 5-34
7 x IN (y) Any Same as x Boolean 5-40
6 BETWEEN x AND y Any Same as x Boolean 5-40
5 x IS NULL Any or Large Boolean 5-36
4 NOT y Boolean Boolean 5-33
3 x AND y Boolean Boolean Boolean 5-33
2 x OR y Boolean Boolean Boolean 5-33
1 ASCII y INT or SMALLINT Character 7-60
x CLIPPED Character Character 5-44
COLUMN y INT or SMALLINT Character 7-60
ORD(y) Character INT or SMALLINT 5-94
x SPACES INT or SMALLINT Character 7-62
x USING "y" Character,DATE,MONEY Character Character 5-115
x WORDWRAP Character or TEXT Character 7-63
3-56 INFORMIX- 4GL Reference Manual
Components of 4GL Expressi ons
Also of lowest precedence (P = 1) are the following operators:
B Field operators FIELD_TOUCHED( ), GET_FLDBUF( ), and INFIELD( )
B Report operators SPACE, LINENO, and PAGENO
B Time operators CURRENT, DATE( ), DAY( ), EXTEND( ), MDY( ),
MONTH( ), TIME, TODAY, WEEKDAY( ), and YEAR( )
Where no data type is listed in the previous table, the operator has no left (or
else no right) operand. If an operand is not of the data types listed here, 4GL
attempts data type conversion, as described in Summary of Compatible
4GL Data Types on page 3-45.
Most 4GL operators do not support RECORD nor ARRAY operands, but they
can accept as an operand a variable (of a simple data type) that is an element
of an array, or that is a member of a record.
Operands in 4GL Expressions
Operands of 4GL expressions can be any of the following:
B Named values.
B Function calls that return one value.
B Literal values.
B Other 4GL expressions.
Sections that follow describe these operands of 4GL expressions
Data Types and Expressi ons 3-57
Components of 4GL Expressi ons
Named Values as Operands
A4GL expression can include the name of a variable of any simple data type
(as identied in Simple Data Types on page 3-9) or the constants TRUE,
FALSE, or NOTFOUND. The variable can also be a simple member of a record
or a simple element of an array.
Element Description
array is the name of a structured variable of the ARRAY data type. The
comma-separated expression list species the index of an element
within the declared size of the array.
constant is one of the built-in constants TRUE, FALSE, or NOTFOUND.
record is the name of a structured variable of the RECORD data type.
variable is the name of a 4GL program variable of a simple data type.
Named Value
Integer
Expression
p. 3-63
,
[
array ] 3
record
variable
1
.
constant
Variable
Variable
3-58 INFORMIX- 4GL Reference Manual
Components of 4GL Expressi ons
In three special cases, other identiers can be operands in 4GL expressions:
B Conditional COLOR attributes in form specication les can use a
eld tag where a named value is valid in the syntax of a 4GL Boolean
expression.
B The built-in FIELD_TOUCHED( ), GET_FLDBUF( ), and INFIELD( )
operators can take eld names (as described in Field Clause on
page 3-87) as operands. See Chapter 5, Built-In Functions and
Operators, for the syntax of these eld operators.
B The identier of a BYTE or TEXT variable can be the operand of the
IS NULL and IS NOT NULL Boolean operators.
If the variable is a member of a record, qualify it with the record name prex,
separated by a period ( . ) as the record membership operator.
Variables of the BYTE or TEXT data types cannot appear in expressions, except
as operands of the IS NULL or IS NOT NULL operators or (for TEXT variables
only) the WORDWRAP operator. These operators are described in Chapter 5.
Function Calls as Operands
A4GL expression can include calls to functions that return exactly one value.
The functioncanbe a programmer-denedor built-infunction, providedthat
it returns a single value of a data type that is valid in the expression.
(Function calls as arguments can return multiple values.)
Element Description
function is the name of a function. The parentheses are required, regardless of
whether the function takes any arguments.
Function Call
,
function
4GL
Expression
p. 3-49
(
)
Data Types and Expressi ons 3-59
Components of 4GL Expressi ons
For information about this statement, see FUNCTION on page 4-143, and
see Chapter 5 for more information about declaring, dening, and invoking
4GL functions.
Expressions as Operands
Two expressions cannot appear consecutively without some separator, but
you can nest expressions within expressions. In any context, however, the
complexity of a 4GL expression is restricted. If an error message indicates that
an expression is too complex, you should substitute two or more simpler
expressions that 4GL can evaluate, and then combine these values.
If an expression returns a different data type from what 4GL expects in the
context, 4GL attempts data type conversion, as described in Summary of
Compatible 4GL Data Types on page 3-45.
3-60 INFORMIX- 4GL Reference Manual
Bool ean Expressi ons
Boolean Expressions
In 4GL, a Boolean expression is one that returns either TRUE (dened as 1)
or FALSE (dened as 0) or (in some contexts) null. The syntax of Boolean
expressions in 4GL statements is not identical to that of Boolean conditions in
SQL statements. Boolean expressions of 4GL have the following syntax.
NOT
OR
Boolean
Expression
Boolean Comparison
TRUE
AND
NULL Test
p. 5-36
String Comparison
p. 5-37
4GL Expression
p. 3-49
Boolean
Comparison
Relational Comparison
p. 5-35
Function Call
p. 3-58
FALSE
Membership and Range Tests
p. 5-40
Data Types and Expressi ons 3-61
Bool ean Expressi ons
Logical Operators and Boolean Comparisons
The following Boolean operators can appear in 4GL Boolean expressions:
B The logical operators AND, OR, andNOT combine one or more Boolean
values into a single Boolean expression.
B Boolean comparisons can test operands and return Boolean values:
O Relational comparisons test for equality or inequality.
O The IS NULL operator tests for null values.
O The MATCHES or LIKE operators compare character strings.
O The BETWEENAND operator compares a value to a range.
O The IN( ) operator tests a value for set membership.
Data Type Compatibility
Any type of 4GL expression can also be a Boolean expression. You can use an
INT or SMALLINT variable to store the returned TRUE, FALSE, or NULL value.
You may get unexpected results, however, from Boolean comparisons of
operands of dissimilar data types. In general, youcan compare numbers with
numbers, character strings with strings, and time values with time values.
If a time expression operand of a Boolean expression is of the INTERVAL data
type, any other time expression to which it is compared by a relational
operator must also return an INTERVAL value. You cannot compare a span of
time (an INTERVAL value) with a point in time (a DATE or DATETIME value).
See Summary of Compatible 4GL Data Types on page 3-45 for additional
information about data type compatibility in 4GL expressions.
3-62 INFORMIX- 4GL Reference Manual
Bool ean Expressi ons
Evaluating Boolean Expressions
Incontexts where a Booleanexpressionis expected, 4GL applies the following
rules after it evaluates the expression:
B If the value is a non-zero real number or any of the following items:
O Character string representing a non-zero number
O Non-zero INTERVAL
O Any DATE or DATETIME value
O A TRUE value returned by a Boolean function like INFIELD( )
O The built-in integer constant TRUE
then the Boolean expression returns TRUE.
B If an expression that returns NULL is the operand of the IS NULL
operator, the value of the Boolean expression is TRUE.
B If the value is NULL and the expression does not appear in any of the
following contexts:
O The NULL Test (page 5-36)
O Boolean Comparisons (page 5-34)
O Any conditional statement of 4GL (IF, CASE, WHILE)
then the Boolean expression returns NULL.
B Otherwise, the Boolean expression is evaluated as FALSE.
Boolean expressions in CASE, IF, or WHILE statements return FALSE if any
element of the comparison is NULL, except for operands of the IS NULL and
the IS NOT NULL operator. See Boolean Operators on page 5-33 for more
information about individual Boolean operators and Boolean expressions.
If you include a Boolean expression in a context where 4GL expects a number,
the expression is evaluated, and is then converted to an integer by the rules:
TRUE = 1 and FALSE = 0.
Data Types and Expressi ons 3-63
Integer Expressi ons
Integer Expressions
An integer expression returns a whole number. It has the following syntax.
Here any function call or named value must return an integer. Logical restric-
tions on using DATE values as integer expressions are discussed in
Arithmetic Operations on Time Values on page 3-83.
Integer expressions can be components of expressions of every other type.
Like Boolean expressions, integer expressions are a logical subset of number
expressions, but they are separately described here because some 4GL
operators, statements, form specications, operators, and built-in functions
are restricted to integer values, or to positive integers.
Case I: Pure i ntegers
MOD
**
+
-
*
/
Literal Integer
p. 3-65
Function Call
p. 3-58
Named Value
p. 3-57
-
+
Boolean
Expression
p. 3-60
-
DATE Expression
p. 3-74
DATE Expression
p. 3-74
Integer
Expression
Case II: Di fferences between DATE val ues
3-64 INFORMIX- 4GL Reference Manual
Integer Expressi ons
Binary Arithmetic Operators
Six binary arithmetic operators can appear in an integer expression, and can
take integer expressions as both the right-hand and left-hand operands.
All arithmetic calculations are performed after converting both operands to
DECIMAL values (but MOD operands are rst converted to INTEGER).
If an expression has several operators of the same precedence, 4GL processes
them from left to right. See Figure 3-2 on page 3-54 for the complete prece-
dence scale for 4GL operators. If any operand of an arithmetic expression is
a NULL value, the entire expression returns NULL.
An integer expression specifying an array element or the right-hand MOD
operand cannot include exponentiation (**) or modulus (MOD) operators,
and cannot be zero. The right-hand integer expression operand of the
exponentiation operator (**) cannot be negative. You cannot use mod as a
4GL identier.
If both operands of the division operator ( / ) have INT or SMALLINT data
types, 4GL discards any fractional portion of the quotient. An error occurs if
the right-hand operand of the division operator evaluates to zero. With some
restrictions, 4GL also supports these binary arithmetic operators in number
expressions (as described in Number Expressions on page 3-66) and in
some time expressions (as described in Time Expressions on page 3-72).
Differences between two DATE values are integer expressions. To convert
these to type INTERVAL, apply the UNITS DAY operator explicitly.
Operator Symbol Operator Name Name of Result Precedence
** Exponentiation Power 12
mod Modulus Integer remainder 12
* Multiplication Product 11
/ Division Quotient 11
+ Addition Sum 10
- Subtraction Difference 10
Data Types and Expressi ons 3-65
Integer Expressi ons
As noted earlier in this chapter, if you include a Boolean expression in a
context where 4GL expects a number, the expression is evaluated, and is then
converted to an integer by the rules: TRUE = 1 and FALSE = 0. An error results
if you attempt to divide by zero.
Unary Arithmetic Operators
You can use plus ( + ) and minus ( - ) symbols at the left are unary operators to
indicate the sign of the expression, or the sign of a component number. For
unsigned values, the default is positive ( + ). Use parentheses to separate the
subtraction operator ( - ) fromany immediately following unary minus sign,
as in the following:
minuend -(-subtrahend)
unless you want 4GL to interpret the -- symbols as a comment indicator.
The same rules apply to plus and minus unary operators used with number
expressions, and with time expressions that return INTERVAL values.
The unary plus and minus operators are recursive.
Literal Integers
You must write literal integers in base-10 notation, without embedded blank
spaces or commas, and without a decimal point.
This release of 4GL does not support non-ASCII digits in number expressions,
such as the Hindi numbers that some Middle-Eastern locales recognize.
Element Description
digit is any of the digits 1, 2, 3, 4, 5, 6, 7, 8, 9, or 0.
+
digit
-
Literal
Integer
GLS
3-66 INFORMIX- 4GL Reference Manual
Number Expressi ons
You can precede the integer with unary minus or plus signs:
15 -12 13938 +4
Number Expressions
A number expression is a specication that evaluates to a real number.
Here the function call or named value must return a real number of data type
DECIMAL, FLOAT, INTEGER, MONEY, SMALLFLOAT, or SMALLINT.
If any operand of an arithmetic operator in a number expression is a null
value, 4GL evaluates the entire expression as a NULL value. The range of
values in a number expression is that of the receiving data type.
Arithmetic Operators
The sections Binary Arithmetic Operators on page 3-64 and Unary Arith-
metic Operators on page 3-65 apply to number expressions. 4GL converts
any modulus (MOD) operand or right-hand operand of the exponentiation
operator (**) to INTEGER before conversion to DECIMAL for evaluation; this
feature has the effect of discarding any fractional part of the operands.
If both operands are INTEGER, SMALLINT, or DATE data types, the result of
any arithmetic operation (including division) is a whole number. If either
operand is of data type DECIMAL, FLOAT, MONEY, or SMALLFLOAT, the
returned value may include a fractional part, except in MOD operations.
MOD
**
+
-
*
/
Boolean
Expression
p. 3-60
Literal Number
p. 3-67
Number
Expression
Function Call
p. 3-58
Named Value
p. 3-57
-
+
Integer
Expression
p. 3-63
Data Types and Expressi ons 3-67
Number Expressi ons
Literal Numbers
A literal number is the base-10 representation of a real number, written as an
integer, as a xed-point decimal number, or in exponential notation.
This cannot include a comma ( , ) or blank space (ASCII 32). The unary plus
or a minus sign can precede a literal number, mantissa, or exponent.
This release of 4GL does not support non-ASCII digits in literal numbers, such
as the Hindi numbers that some Middle-Eastern locales recognize.
There are three kinds of literal numbers:
B Integer literals canexactly represent INTEGERandSMALLINT values.
Literal integers have no decimal points, as in this example:
10 -27 25567
B Fixed-point decimal literals can exactly represent DECIMAL(p,s) and
MONEY values. These can include a decimal point:
123.456.00123456 -123456.0
B Floating-point literals can exactly represent FLOAT, SMALLFLOAT,
and DECIMAL(p) values that contain a decimal point or exponential
notation, or both. These are examples of oating-point literals:
123.456e4-1.23456e2-123456.0e-3
When you use a literal number to represent a MONEY value, do not precede
it with a currency symbol. Currency symbols are displayed by 4GL when
MONEYvalues appear in a formor in a report, using whatever the DBMONEY
or DBFORMAT environment variable species, or else the default symbol,
which in the default (U.S. English locale) is the dollar sign ( $ ).
digit
E
-
+
digit
e
Literal
Number
.
digit
.
-
+
Element Description
digit is any of the digits 1, 2, 3, 4, 5, 6, 7, 8, 9, or 0.
GLS
3-68 INFORMIX- 4GL Reference Manual
Character Expressi ons
In other locales, DBMONEY or DBFORMAT can specify number and currency
display and data entry formats to conformwith local cultural conventions.
4GL automatically attempts data type conversion when a literal number is in
a different format from the expected data type. If you include a character
value in a context that requires a number expression, 4GL attempts to convert
the string to a number. (For more information, see Summary of Compatible
4GL Data Types on page 3-45.)
You may get unexpected results, however, if a literal number in a 4GL
Boolean expression is not in a format that can exactly represent the data type
of another value with which it is compared by a relational operator. Because
of rounding errors, for example, relational operators generally cannot return
TRUE if one operand returns a FLOAT value and the other an INTEGER.
Similarly, you will get unpredictable (but probably useless) results if you use
literal binary, hexadecimal, or other numbers that are not base-10 where 4GL
expects a number expression. You must convert such numbers to a base-10
format before you can use them in a number expression.
Character Expressions
A character expression is a specication that evaluates to a character string.
GLS
Integer
Expression
p. 3-63
CLIPPED Function Call
p. 3-58
Named Value
p. 3-57
character
[
]
,
" "
Character
Expression
Integer
Expression
p. 3-63
USING
"format
string "
Data Types and Expressi ons 3-69
Character Expressi ons
Here the function call or named value returns a CHAR or VARCHAR value.
No variable in a character expression can be of the TEXT data type, except in
a NULL test (as described in The NULL Test on page 5-36), or as a
WORDWRAP operand in a PRINT statement of a 4GL report. As in any 4GL
statement or expression, you cannot reference a named value outside its
scope of reference. (See Scope of Reference of 4GL Identiers on page 2-17.)
If a character expression includes a 4GL variable or function whose value is
neither a CHAR nor VARCHAR data type, 4GL attempts to convert the value
to a character string. For example, the following programfragment stores the
character string "FAX32" in the CHAR variable K:
VARIABLE I INTEGER,
J, K CHAR(5)
LET I = 4*8
LET J = "FAX"
LET K = J CLIPPED,I
The maximum length of a string value is the same as for the declared data
type: up to 32,767 bytes for CHAR values, and up to 255 bytes for VARCHAR.
If character expressions are operands of a relational operator, 4GL evaluates
both character expressions, andthen compares the returnedvalues according
to their position within the collating sequence of the locale. For more infor-
mation, see Relational Operators on page 5-35.
Arrays and Substrings
Any integer expression in brackets that follows the name of an array must
evaluate to a positive number within a range from 1 to the declared size of
the array. For example, SQLCA.SQLCAWARN[6] species the sixth element of
character array SQLCAWARN within the SQLCA global record.
Element Description
character is one or more characters enclosed between two single ( ' ) or double
( " ) quotation marks. (This is sometimes called a character string, a
quoted string, or a string literal.)
format string is a formatting mask to specify how4GL displays the returned
character value. (See USING on page 5-115 for details.)
3-70 INFORMIX- 4GL Reference Manual
Character Expressi ons
The pair of integer expressions that can followa character expression specify
a substring. The rst value cannot be larger than the second. Both must be
positive, and no larger than the string length (or the receiving data type). For
example, name[1,4] species the rst four characters of a program variable
called name.
Neither the exponentiation (**) nor the modulus (MOD) operators can
appear in an integer expression that species an array element or a substring,
but parentheses and the other arithmetic operators ( +, -, *, / ) are permitted.
String Operators
You can use the USING keyword, followed by a format string, to impose a
specic format on the character string to which an expression evaluates, or
upon any components of a concatenated character expression. (4GL forms
and reports support additional features for formatting character values.)
To discardtrailing blanks froma character value, apply the CLIPPEDoperator
to the expression, or to any components of a concatenated character
expression. For more information about handling blank characters in
character values, see the sections of Chapter 5 that describe the WORDWRAP
eld attribute in forms and the WORDWRAP operator in 4GL reports, and see
The WORDWRAP Operator on page 7-63.
You can insert blanks in DISPLAY or PRINT statements by using the SPACE or
COLUMN operators; these are described in Chapter 5. The keyword SPACES
is a synonym for SPACE.
You can use the ASCII operator in DISPLAY or PRINT statements. This takes
an integer expression as its operand, and returns a single-character string,
corresponding to the specied ASCII character. See Chapter 5 for details.
Non-Printable Characters
In the default (U.S. English) locale, 4GL regards the following as the printable
ASCII characters:
B TAB (= CONTROL-I)
B NEWLINE (= CONTROL-J)
B FORMFEED (= CONTROL-L)
B ASCII 32 (= blank) through ASCII 126 (= ~)
Data Types and Expressi ons 3-71
Character Expressi ons
For information about the ASCII characters and their numeric codes, see
Appendix G, Reserved Words. Any other characters are non-printable.
Character strings that include one or more non-printable characters (for
example, packed elds) can be operands or returned values of character
expressions. They can be stored in 4GL variables or in database columns of
the CHAR, VARCHAR, and TEXT data types.
You should be aware, however, that many 4GL features for manipulating
character strings were designed for printable characters only. If you create
4GL applications that use character expressions, character variables, or
character columns to manipulate non-printable characters, you may
encounter unexpected results. The following are examples of problems that
you risk when CHAR, TEXT, and VARCHAR values include non-printable
characters.
B Behavior of I/O and formatting features like the WORDWRAP
attribute or the DISPLAY or PRINT statements is designed and
documented for printable characters only. It may be difficult to
describe or to predict the effects of data with non-printable
characters with these I/O features, but the users of your application
are unlikely to enjoy the results.
B Strings with non-printable characters can have unpredictable results
when output to I/O devices. For example, some sequences of non-
printable characters can cause terminals to position the cursor in the
wrong place, clear the display, modify terminal attributes, or
otherwise make the screen unreadable.
B For another example, CONTROL-D (= ASCII 4) and CONTROL-Z
(= ASCII 26) in output froma report can be interpreted as logical end-
of-le, causing the report to stop printing prematurely.
B If you store a zero byte (ASCII 0) in a CHAR or VARCHAR variable or
column, it might be treated as a string terminator by some operators,
but as data by others, and this behavior might vary between the
Rapid Development Systemand the C Compiler implementation of
4GL, or even between database servers. The workaround is to not use
the ASCII 0 character within CHAR or VARCHAR data strings.
If you encounter these or related difficulties in processing non-printable
characters, you might consider storing such values as BYTE data types.
3-72 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
Nondefault locales can dene other non-printable characters. The
DBAPICODE environment variable lets computer peripherals that use a
character set that is different fromthat of the database communicate with the
database. DBAPICODE species the character-mapping le between the
character set of the peripheral device and the character set of the database.
For more information about nondefault locales, see Appendix E.
Time Expressions
A time expression is a specication that 4GL can evaluate as a DATE,
DATETIME, or INTERVAL value.
As the diagramsuggests, the DATE data type is a logical subset of DATETIME.
4GL rules for arithmetic, however, are not identical for DATE and DATETIME
operands, andthe internal storage formats of DATEandDATETIME values are
completely different. (For more information, see Arithmetic Operations on
Time Values on page 3-83.)
Formatting features, suchas USING(describedinChapter 5) andthe FORMAT
and PICTURE attributes (described in Chapter 6, Screen Forms), also treat
DATETIME and DATE values differently or support only DATE.
GLS
Time Expression
INTERVAL Expression
p. 3-74
DATETIME Expression
p. 3-74
DATE Expression
p. 3-74
Data Types and Expressi ons 3-73
Ti me Expressi ons
These three data types are logically related, because they express values in
units of time. But unlike the number and character data types that were
described earlier in this chapter, for which 4GL supports automatic data type
conversion (aside from restrictions based on truncation, overow, or
underow), conversion among time data types is more limited. In contexts
where a time expression is required, DATETIME or DATE values can
sometimes be substituted for one another. INTERVAL values, however, which
represent one-dimensional spans of time, cannot be converted to DATETIME
or DATE values, which represent zero-dimensional points in time.
In addition, if the declared precision of an INTERVAL value includes years or
months, automatic conversion to an INTERVAL having smaller time units
(like days, hours, minutes, or seconds) is not available. See also Summary of
Compatible 4GL Data Types on page 3-45.
3-74 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
Each of the three types of time expressions has its own syntax.
,
TODAY
DATE
Expression
USING f
Function Call
p. 3-58
Named Value
p. 3-57
DATETIME
Expression
EXTEND (
CURRENT
DATETIME Qualier
p. 3-76
)
DATETIME
Expression
DATE
Expression
DATETIME Literal
p. 3-78
Function Call
p. 3-58
Named Value
p. 3-57
DATETIME
Qualier
p. 3-76
INTERVAL
Expression
INTERVAL Literal
p. 3-82
Numeric Time Interval
p. 3-82
Function Call
p. 3-58
Named Value
p. 3-57
Integer Expression
p. 3-63
UNITS
-
+
Character
Expression
p. 3-68
" "
Numeric Date
p. 3-75
" "
Numeric Date and Time
p. 3-78
" "
keyword
Case I: Expressi ons that return a DATE val ue
Case II: Expressi ons that return a DATETIME val ue
Case III: Expressi ons that return an INTERVAL val ue
Data Types and Expressi ons 3-75
Ti me Expressi ons
Here the keyword can be YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, or
FRACTION. The function call or named value must return a single value of the
corresponding data type. Other operators besides those listed here can also
appear intime expressions. Chapter 5 describes built-inoperators like UNITS.
Sections that follow show the syntax of component segments of DATE,
DATETIME, and INTERVAL expressions.
Numeric Date
A numeric date represents a DATE value as a quoted string of digits and
optional separator symbols. For the default locale, it has this format.
The digits must represent a valid calendar date. The default locale supports
6 digits (moddyy) or 8 digits (moddyyyy), with blank, slash ( / ), hyphen ( - ),
no symbol, or any character that is not a digit as separator. Here mo, dd, and
yyyy have the same meanings as in DATETIME Literal on page 3-78.
The DBDATE environment variable can change the order of time units and
can specify other separators. Like the USING operator or the FORMAT eld
attribute, DBDATE can also specify how4GL displays DATE values.
In some East-Asian locales, the GL_DATE environment variable can specify
Japanese or Taiwanese eras for the entry and display of DATE values. (In any
locale, GL_DATE can specify formats beyond what DBDATE can specify.)
Element Description
dd is the number of the day of the month, from 1 to 31.
mo is a number from 1 to 12, representing the month.
separator is any character that is not a digit.
yy is an integer from1 to 99, abbreviating the year. If only a single digit is
supplied, 4GL automatically prexes it with a leading zero.
yyyy is an integer from 1 to 9999, representing the year.
" "
mo
yyyy separator dd separator
Numeric Date
dd yy
GLS
3-76 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
The DBCENTURY environment variable, or CENTURY attribute, determines
howto expand abbreviated year values in DATE (or DATETIME) elds of 4GL
forms. These features can also expand a two-digit year in a PROMPT
statement.
If you omit the quotation marks where a DATE value is expected, 4GL
attempts to evaluate your specication as a literal integer or as an integer
expression specifying a count of days since December 31, 1899. If slash ( / ) is
the separator, the quotient of month and day is divided by the year value,
producing a value that usually rounds to zero, or December 31, 1899. This
result may not be useful, if the logical context requires a more recent date.
DATETIME Qualier
The DATETIMEqualier species the precision andscale of a DATETIME value.
It has the same syntax as the qualiers of DATETIME database columns.
Element Description
scale is an integer (1 scale 5), enclosed between parentheses.
YEAR
MONTH
DAY
MINUTE
SECOND
FRACTION
HOUR
(3)
( scale )
DATETIME Qualier
TO DAY
TO HOUR
TO MINUTE
TO SECOND
TO FRACTION
TO YEAR
TO MONTH
Data Types and Expressi ons 3-77
Ti me Expressi ons
Specify the largest time unit in the DATETIME value as the rst keyword.
After the TO, specify the smallest time unit as the last keyword. These time
units can be recorded in the numeric DATETIME value.
Unlike INTERVAL qualiers, DATETIME qualiers cannot specify nondefault
precision (except for FRACTION when it is the smallest unit in the qualier).
Here are some examples of DATETIME qualiers:
YEAR TO MINUTE MONTH TO MONTH
DAY TO FRACTION(4) MONTH TO DAY
An error results if the rst keyword represents a smaller time unit than the
last, or if you use the plural form of a keyword (such as MINUTES).
YEAR is a year; in numeric values, this can range from 1 to 9999.
MONTH is a month, ranging from 1 to 12.
DAY is a day, ranging from 1 to 31, as appropriate to its month.
HOUR is an hour, ranging from 0 (midnight) to 23.
MINUTE is a minute, ranging from 0 to 59.
SECOND is a second, ranging from 0 to 59.
FRACTION is a fraction of a second, with up to 5 decimal places.
3-78 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
DATETIME Literal
ADATETIME literal is the representation of a DATETIME value as the numeric
date and time, or a portion thereof, followed by a DATETIME qualier.
Element Description
dd is the number of the day of the month, from 1 to 31.
fffff is the fraction of a second, up to 5 digits, as set by the precision specied
for the FRACTION time units in the DATETIME qualier.
hh is the hour (from a 24-hour clock), from 0 (midnight) to 23.
mi is the minute of the hour, from 0 to 59.
mo is a number from 1 to 12, representing the month.
space is a blank space (ASCII 32), entered by pressing SPACEBAR.
ss is the second of the minute, from 0 to 59.
yyyy is a number from 1 to 9999, representing the year. If it has fewer than 3
digits, 4GL expands the year value to 4 digits (according to the
DBCENTURY setting, unless the CENTURY attribute is specied).
) (
yyyy
-
mo
-
dd
space
hh
mi
ss
fffff
:
.
:
DATETIME Qualier
p. 3-76
Numeric Date
and Time
DATETIME
Numeric Date
and Time
DATETIME Literal
Data Types and Expressi ons 3-79
Ti me Expressi ons
An error results if you omit any requiredseparator or include values for units
outside the range specied by the qualier. Here are some examples:
DATETIME (99-3-6) YEAR TO DAY
DATETIME (09:55:30.825) HOUR TO FRACTION
DATETIME (01-5) YEAR TO MONTH
Here is an example of a DATETIME literal used in an arithmetic expression as
an operand of the EXTEND operator:
EXTEND (DATETIME (2000-8-1) YEAR TO DAY, YEAR TO MINUTE)
- INTERVAL (720) MINUTE (3) TO MINUTE
The DBCENTURY environment variable setting determines howsingle-digit
and two-digit year specications in DATETIME elds of 4GL forms are
expanded. For more information, see Appendix D, Environment Variables.
The CENTURY attribute of 4GL forms can specify the same algorithms as
DBCENTURY for expanding abbreviated year values. Unlike DBCENTURY ,
however, which species a single default algorithmfor the entire application,
CENTURY species the expansion rule for a single eld. If the two settings are
different, the CENTURY setting takes precedence (within its eld) over the
DBCENTURY setting. For more information, see DBCENTURY on
page D-15 and CENTURY on page 6-36. The PROMPT statement also
supports a CENTURY attribute for DATETIME (or DATE) values that the user
enters with the year abbreviated.
The GL_DATETIME environment variable can specify display and data entry
formats for DATETIME values to conform with local cultural conventions,
such as Japanese or Taiwanese eras for year values in some East-Asian
locales.
GLS
3-80 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
INTERVAL Qualier
The INTERVAL qualier species the precision and scale of an INTERVAL
value. It has the same syntax in 4GL as for INTERVAL database columns.
Any intermediate time units between the rst and last keywords that you
specify in an INTERVAL qualier have the default precision of 2 digits.
Case II: Ti me uni ts greater than DAY
Case I: Ti me uni ts smal l er than MONTH
DAY
MINUTE
SECOND
FRACTION
TO DAY
TO HOUR
TO MINUTE
TO SECOND
TO FRACTION
HOUR
(precision)
(precision)
(precision)
(precision)
( scale )
YEAR
MONTH
TO YEAR
TO MONTH
(precision)
(precision)
(2)
(2)
(2)
(2)
(4)
(3)
INTERVAL
Qualier
(2)
Element Description
scale is the number of decimal digits to record fractions of a second in a span
of time. The default is 3 digits; the maximum is 5.
precision is the number of digits in the largest time units that the interval can
include. The maximumnumber of digits is 9; the default is 2 (except for
the number of years, whose default precision is 4).
Data Types and Expressi ons 3-81
Ti me Expressi ons
If the INTERVAL value can include more than one different time unit, specify
the largest time unit in the INTERVAL as the rst keyword. After the TO,
specify the smallest time unit as the last keyword. If the rst time unit
keyword is YEAR or MONTH, the last cannot be smaller than MONTH.
The following examples of an INTERVAL qualier are both YEAR TOMONTH.
The rst example can record a span of up to 999 years, because 3 is the
precision of the YEAR units. The second example uses the default precision
for the YEAR units; it can record a span of up to 9999 years and 11 months.
YEAR (3) TO MONTH
YEAR TO MONTH
When you intend for a value to contain only one kind of time unit, the rst
and last keywords in the qualier are the same. For example, an interval of
whole years that is qualied as YEARTOYEAR can record a span of up to 9999
years, the default precision. Similarly, the qualier YEAR (4) TO YEAR can
record a span of up to 9,999 years.
The following examples show several forms of INTERVAL qualiers:
YEAR(5) TO MONTH
DAY (5) TO FRACTION(2)
DAY TO DAY
FRACTION TO FRACTION (4)
The option to specify a nondefault precision or y-precision (as distinct from
the scale) is a feature that INTERVAL variables do not share with DATETIME
variables. An error results if you attempt to do this when you declare a
DATETIME variable, specify DATETIME literal, or call the EXTEND operator.
An error also results if the rst keyword represents a smaller time unit than
the last, or if you use the plural form of a keyword (such as MONTHS).
3-82 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
INTERVAL Literal
An INTERVAL literal represents a span of time as a numeric representation of
its chronological units, followed by an INTERVAL qualier.
Element Description
dd is the number of days.
fffff is the fraction of a second, up to 5 digits, depending on the precision of
the fractional portion in the INTERVAL qualier.
hh is the number of hours.
mi is the number of minutes.
mo is the number of months, in 2 digits.
(1 of 2)
Numeric Time Interval
INTERVAL
Literal
( ) Numeric Time Interval
INTERVAL
INTERVAL
Qualier
p. 3-80
Case II: Ti me uni ts greater than DAY
dd
space
hh
mi
ss
fffff
.
-
:
:
yyyy
-
mo
-
Case I: Ti me uni ts smal l er than MONTH
+
+
Data Types and Expressi ons 3-83
Ti me Expressi ons
For all time units except years and fractions of a second, the maximum
number of digits allowed is two, unless this is the rst time unit, and the
precision is specied differently by the INTERVAL qualier. (For years, the
default maximum number of digits is four, unless some other precision is
specied by the INTERVAL qualier.
Neither the numeric values nor the qualier can combine units of time that
are smaller than month with month or year time units.
An error results if an INTERVAL literal omits any required eld separator, or
includes values for units outside the range specied by the eld qualiers.
Some examples of INTERVAL literal values follow:
INTERVAL (3-6) YEAR TO MONTH
INTERVAL (09:55:30.825) HOUR TO FRACTION
INTERVAL (40-5) DAY TO HOUR
Arithmetic Operations on Time Values
Time expressions can be operands of some arithmetic operators. If the result
is within the range of valid DATE values, these expressions return a DATE
value.
space is a blank space (ASCII 32), entered by pressing SPACEBAR.
ss is the number of seconds.
yyyy is the number of years.
Element Description
(2 of 2)
DATE Expression
p. 3-74
-
-
+
Integer
Expression
p. 3-63
DATE
Expression
p. 3-74
+
Integer
Expression
p. 3-63
3-84 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
All the other binary arithmetic operators (listedinArithmetic Operators on
page 3-66) also accept DATE operands, equivalent to the count of days since
December 31, 1899, but the values returned (except from a DATE expression
as the left-hand MOD operand) are meaningless in most applications.
DATE and DATETIME values have no true zero point; they lie on interval
scales. Such scales can logically support addition and subtraction, as well as
relational operators (as described in Relational Operators and Time Values
on page 3-86), but multiplication, division, and exponentiation are
undened.
The difference between two DATE values is an INTEGER value, representing
the positive or negative number of days between the two calendar dates. You
must explicitly apply the UNITS DAY operator to the difference between
DATE values if you wish to store the result as an INTERVAL value.
This is the syntax for arithmetic expressions that return a DATETIME value.
Do not write expressions that specify the sum( + ) of two DATE or DATETIME
values, or a difference ( - ) whose second operand is a DATE or DATETIME
value, and whose rst operand is an INTERVAL value.
DATETIME Expression
p. 3-74
DATE Expression
p. 3-74
INTERVAL Expression
p. 3-74
( )
INTERVAL Expression
p. 3-74
-
+
( ) DATETIME Expression
p. 3-74
INTERVAL Expression
p. 3-74
INTERVAL Expression
p. 3-74
DATE Expression
p. 3-74
+
Data Types and Expressi ons 3-85
Ti me Expressi ons
This is the syntax for arithmetic expressions that return an INTERVAL value.
The difference between two DATETIME values (or a DATETIME and a DATE
value, but not two DATE values) is an INTERVAL value.
An expression cannot combine an INTERVAL value of precision in the range
YEAR TO MONTH with another of precision in the DAY TO FRACTION range.
Similarly, you cannot combine an INTERVAL value with a DATETIME or DATE
value that has different qualiers. You must use EXTEND to change the DATE
or DATETIME qualier to match that of the INTERVAL value.
If the rst operand of an arithmetic expression includes the UNITS operator
(page 5-111), you must enclose that operand in parentheses.
If any component of a time expression is a NULL value, 4GL evaluates the
entire expression as NULL.
DATETIME or INTERVAL operands in arithmetic cannot be quoted strings
representing numeric date and time (page 3-78) or numeric time interval
(page 3-82) values. Use instead DATETIME or INTERVAL literals that also
include appropriate DATETIME or INTERVAL qualiers. For example, the
following LET statement that attempts to include an arithmetic expression
LET totalsec = "2002-01-01 00:00:00.000" - "1993-01-01 00:00:00.000"
in fact assigns a NULL value to the INTERVAL variable totalsec, rather than
an interval of 9 years, because the two operands have no qualiers. Better is
LET totalsec = DATETIME (2002-01-01 00:00:00.000) YEAR TO FRACTION
- DATETIME (1993-01-01 00:00:00.000) YEAR TO FRACTION
DATETIME Expression
p. 3-74
INTERVAL Expression
p. 3-74
-
+
( )
DATETIME Expression
p. 3-74
/
-
*
-
Number Expression
p. 3-66
DATE Expression
p. 3-74
DATE Expression
p. 3-74
INTERVAL Expression
p. 3-74
INTERVAL
Expression
p. 3-74
INTERVAL Expression
p. 3-74
( )
3-86 INFORMIX- 4GL Reference Manual
Ti me Expressi ons
Arithmetic with the UNITS operator or INTERVAL operands can return
invalid dates. For example, (5 UNITS MONTH) + DATETIME (1999-9 30)
YEAR TO DAY produces an error (-1267: The result of a datetime compu-
tation is out of range,) because the returned value (2000-2 30) is not
a valid calendar date.
Relational Operators and Time Values
Time expression operands of relational operators follow these rules:
B Comparison x < y is TRUE when x is a briefer INTERVAL span than y,
or when x is an earlier DATE or DATETIME value than y.
B Comparison x > y is TRUE when x is a longer INTERVAL span than y,
or when x is a later DATE or DATETIME value than y.
B You cannot mix INTERVAL with DATE or DATETIME operands; but
you can compare DATE and DATETIME values with each other.
Data Types and Expressi ons 3-87
Fi el d Cl ause
Field Clause
The eld clause species one or more screen elds or screen records.
Element Description
eld is a eld name, as declared in the ATTRIBUTES section of the form
specication le.
line is aninteger expression, enclosedwithinbrackets, to specify a record
within the screen array. Here 1 line size, where size is the array
size that is declared in the INSTRUCTIONS section. If you omit the
[line] specication, the default is the rst record.
screen array is the 4GL identier that you declared for a screen array in the
INSTRUCTIONS section of the form specication le.
screen record is the 4GL identier that you declared for a screen record, or else a
table reference (as the name of a default screen record).
table is the name, alias, or synonym of a database table or view.
Field Clause
,
.
*
eld
THRU
Notation
p. 3-93
[ line ]
[ 1 ]
table
screen
record
screen
array
FORMONLY
3-88 INFORMIX- 4GL Reference Manual
Usage
Usage
Atable reference cannot include table qualiers. You must declare an alias in
the form specication le, as described in Table Aliases on page 6-24, for
any table reference that requires a qualifying prex (such as database, server,
or owner). Here the FORMONLY keyword acts like a table reference for elds
that are not associated with a database column. For more information, see
FORMONLY Fields on page 6-29.
You can use an asterisk ( * ) to specify every eld in a screen record.
Some contexts, such as the NEXT FIELD clause, support only a single-eld
subset of this syntax. In these contexts, the THRU or THROUGH keyword,
asterisk notation, and comma-separated list of eld names are not valid.
You can specify one or more of the following in the eld clause:
B A eld name without qualiers (eld) if this name is unique in the
form
B A eld name, qualied by a table reference (FORMONLY.eld or
table.eld)
B An individual member of a screen record (record.eld)
B An individual eld within a screen array (array [line].eld)
B A set of consecutive elds in a screen record (by the THRU notation)
B An entire screen record (record.*)
B The rst screen record in a screen array (array.* )
B Any entire record within a screen array (array [line].*)
Important: Some 4GL statements support only a subset of these features. For
example, CONSTRUCT cannot specify a screen array line below the rst. Similarly,
the FIELD_TOUCHED( ) operator in a CONSTRUCT or INPUT statement does not
support the [line] notation to specify a screen record within a screen array.
The eld list of a SCREENRECORDspecication in the INSTRUCTIONS section
of a screen formcan include the THRU or THROUGH keywords. (For details,
see THRU or THROUGH Keywords and .* Notation on page 3-93.)
Chapter 6 describes how to declare screen records and screen arrays.
The following INPUT statement illustrates how to specify a eld name:
INPUT p_customer.fname, p_customer.lname FROM fname, lname
Data Types and Expressi ons 3-89
References
The following SCROLL statement moves the displayed values in all the elds
of the s_orders screen array downwards by two lines. Any values are cleared
fromthe rst two screen records; any values in the two screen records that are
closest to the bottom of the 4GL screen or other 4GL windows are no longer
visible:
SCROLL s_orders.* DOWN 2
The next SCROLL statement moves the displayed values in two of the elds
of the s_orders screen array towards the top of the 4GL screen for every
screen record. Any other elds of the s_orders array are not affected:
SCROLL s_orders.stock_num, s_orders.unit_descr UP 2
The following CLEAR statement clears one record of a screen array. In this
example, the integer value of the idx variable determines whichscreenrecord
is cleared:
CLEAR s_items[idx].*
References
CLEAR, CONSTRUCT, DISPLAY, INPUT, INPUT ARRAY, SCROLL, THRU
3-90 INFORMIX- 4GL Reference Manual
Tabl e Qual i ers
Table Qualiers
Statements that reference database tables, views, or synonyms (either alone
or as qualiers of database column names) can include table qualiers.
Usage
Table qualiers can appear in SQL and other 4GL statements and in table alias
declarations in the TABLES section of form specications. You cannot,
however, prex a table alias or a eld name with a table qualier. Except in
table alias declarations within the TABLES section, you cannot include table
qualiers anywhere in a form specication le.
Owner Naming
The qualier can specify the login name of the owner of the table. You must
specify owner if table.column is not a unique identier within its database.
In an ANSI-compliant database, you must qualify each table name with that
of the owner of the table (owner.table). The only exception is that you can omit
the owner prex for any tables that you own.
Element Description
database is the name of a database containing the table, view, or synonym.
owner is the login name of the owner of the table, view, or synonym whose
identier immediately follows the table qualier.
server is the name of the host systemwhere database resides. Blank spaces are
not valid after the @ symbol.
@server
database :
owner.
"owner."
Table Qualier
IDS
'owner.'
ANSI
Data Types and Expressi ons 3-91
Tabl e Qual i ers
If the current database is ANSI-compliant, a runtime error results if you
attempt to query a remote database that is not ANSI-compliant.
For example, if Les owns table t1, you own table t2, and Sasha owns table t3,
you could use the following statement to reference three columns in those
tables:
VALIDATE var1, var2, var3 LIKE les.t1.c1, t2.c2, sasha.t3.c3
You can include the owner name in a database that is not ANSI-compliant. If
owner is incorrect, however, 4GL generates an error. For more information, see
the discussion of the Owner Name segment in the Informix Guide to SQL:
Syntax.
Database References
The LIKE clause of 4GL statements like DEFINE, INITIALIZE, and VALIDATE
can use this database: or database@server: notation in table qualiers to specify
tables in a database other than the default database (as described in The
Default Database at Compile Time on page 4-75). Without such qualiers,
4GL looks for the table in the default database. Even if the table qualier
includes a database reference, however, the LIKE clause will fail unless you
also include a DATABASE statement before the rst program block in the
same module to specify a default database.
The current database is the database specied by the most recently executed
DATABASE statement in a MAIN or FUNCTION program block in the same
module. 4GL programs can include SELECT statements that query a table in
an Informix Dynamic Server database that is not the current database, but
they cannot insert, update, or delete rows from any table that is not in the
current database.
If the current database is supported by Informix Dynamic Server, a table
reference can also include @server to specify the name of another host system
on which a table resides.
LOAD FROM "fyl" INSERT INTO dbas@hostile:woody.table42
Only the databases storedin your current directory, or in a directory specied
in your DBPATH environment variable, are recognized. Table qualiers
cannot include references to an INFORMIX-SE database.
SE
3-92 INFORMIX- 4GL Reference Manual
Tabl e Qual i ers
References
DATABASE, DEFINE, INITIALIZE, LOAD, VALIDATE, UNLOAD
Data Types and Expressi ons 3-93
THRU or THROUGH Keywords and .* Notati on
THRU or THROUGH Keywords and . * Notation
To list consecutive set members in the order of their declaration, you can use
the .* notation to specify the entire set, or you can use the keyword THRU(or
THROUGH, its synonym) to specify a subset of consecutive members.
record
Integer Expression
p. 3-63
,
[
array
1
]
.
record
THRU
THROUGH
Table
Qualier
p. 3-90
last
same .
THRU
Notation
Program
or Screen
Record
Program
or Screen
Record
.
rst
table
.
*
3
Element Description
array is the name of an ARRAY variable or screen array, or the keyword
FORMONLY. (But if array is not a variable, no loop is allowed.)
rst is the name of some member variable or eld of record.
last is a variable or eld that was declared later than rst.
record is the name of a program record or screen record.
same is the name of the same record that qualied rst.
table is the name, alias, or synonym of a database table.
3-94 INFORMIX- 4GL Reference Manual
THRU or THROUGH Keywords and .* Notati on
Usage
These notational devices in 4GL statements can simplify lists of structured
sets of elds of a screen record or member variables of a program record, or
can indicate all of the columns of a database table or view.
The columns of a database table can be referenced by the asterisk notation,
but you cannot use THRU or THROUGH to specify a partial list of columns.
The notation record.member refers to an individual member variable of a 4GL
programrecord, or a eld of a 4GL screen record. The record.* notation refers
to the entire program record or screen record. Here record can be the name,
alias, or synonym of a table or view, or the name of a program record or
screen record, or the FORMONLY keyword.
The THRU (or equivalently, THROUGH) notation can specify a partial list of
the members of a program record or screen record. The notation record.rst
THRUrecord.last refers to a consecutive subset of members of the record, from
rst through last, where rst appears sooner than last in the data type decla-
ration of a program record, or else in the ATTRIBUTES section of the form
specication le (for screen records).
These notations are a shorthand for writing out a full or partial list of set
members with commas separating individual items in the list; this is the form
to which 4GL expands these notations. Here are two examples:
INITIALIZE pr_rec.member4 THRU pr_rec.member8 TO NULL
DISPLAY pr_rec.* TO sc_rec.*
This INITIALIZE statement sets to null the values of 4GL variables
pr_rec.member4, pr_rec.member5, pr_rec.member6, pr_rec.member7, and
pr_rec.member8. The DISPLAY statement lists the entire record pr_rec in the
screen elds that make up the screen record sc_rec.
The order of record members within the expanded list is the same order in
which they were declared, fromrst to last. For a screen record, this is the
order of their eld descriptions in the ATTRIBUTES section. For example,
suppose that the following lines appeared in the form specication le:
ATTRIBUTES
...
f002=tab3.aa;
f003=tab3.bb;
f004=tab3.cc;
f005=tab2.aa;
f006=tab2.bb;
Data Types and Expressi ons 3-95
THRU or THROUGH Keywords and .* Notati on
f007=tab1.aa;
f008=tab1.bb;
f009=tab1.cc;
...
INSTRUCTIONS
SCREEN RECORD sc_rec (tab3.cc THRU tab1.bb)
This implies the following order of eld names within screen record sc_rec:
tab3.cc tab2.aa tab2.bb tab1.aa tab1.bb
The order of elds in the screen record depends on the physical order of eld
descriptions in the ATTRIBUTES section and on the SCREEN RECORD speci-
cation. The form compiler ignores the physical arrangement of elds in the
screen layout, the order of table names in the TABLES section, the
CONSTRAINED and UNCONSTRAINED keywords of the OPTIONS statement,
and the lexicographic order of the table names or eld names when it
processes the declaration of a screen record. For more information about
default and nondefault screen records, see Screen Records on page 6-74.
The THRU, THROUGH, or .* notation can appear in any list of columns,
elds, or member variables, with the following exceptions:
B THRU or THROUGH cannot reference columns of database tables.
There is no shorthand for a partial listing of columns of a table.
B You cannot use THRUor THROUGHto indicate a partial list of screen
record members while the programdisplays or enters data in a form.
B You cannot use THRU, THROUGH, or .* in a quoted string to specify
variables of a SELECT or INSERT clause in the PREPARE statement.
B You cannot use THRU, THROUGH, or the .* notation to reference a
programrecord that contains an array member. (But these notations
can specify all or part of a record that contains records as members,
or a record that is an element of an array of records.)
B An exception to the general rule of .* expanding to a list of all
column names occurs when .* appears in an UPDATE statement.
Here any columns of the SERIAL data type are excluded from the
expanded list. For example, the following UPDATE statement:
UPDATE table1 SET table1.* = program_rec.*
is equivalent to the expanded syntax:
UPDATE table1 SET table1.col1 = program_rec.member1,
table1.col2 = program_rec.member2, ...
and so forth to the last column, but with any SERIAL column omitted.
3-96 INFORMIX- 4GL Reference Manual
THRU or THROUGH Keywords and .* Notati on
References
CLEAR, CONSTRUCT, DISPLAY, INPUT, INPUT ARRAY, REPORT, SCROLL
Data Types and Expressi ons 3-97
ATTRIBUTE Cl ause
ATTRIBUTE Clause
The ATTRIBUTE clause assigns visual attributes in some 4GL statements.
Usage
Keywords listed at the left of this diagram specify color; those at the right
specify intensity. The ATTRIBUTE clause can appear in the following 4GL
statements:
Besides these statements, both the OPEN WINDOW statement (OPEN
WINDOW on page 4-281) and the OPTIONS statement (OPTIONS on
page 4-293) can include ATTRIBUTE clauses that support additional
keywords, as described in the articles about those statements in Chapter 4.
CONSTRUCT
DISPLAY ARRAY
DISPLAY AT
DISPLAY BY NAME
DISPLAY FORM
DISPLAY TO
ERROR
INPUT
INPUT ARRAY
MESSAGE
PROMPT
BLINK
UNDERLINE
,
ATTRIBUTE ( )
WHITE
RED
CYAN
GREEN
BLUE
BOLD
DIM
INVISIBLE
NORMAL
REVERSE
ATTRIBUTE
Clause
YELLOW
MAGENTA
BLACK
3-98 INFORMIX- 4GL Reference Manual
ATTRIBUTE Cl ause
The DISPLAY ARRAY, INPUT ARRAY, and PROMPT statements support
additional attributes that are described in the next chapter.
You must include at least one keyword in the ATTRIBUTE clause. An attribute
clause in any statement except OPEN WINDOWor OPTIONS can specify zero
or more of the BLINK, REVERSE, and UNDERLINE attributes, and zero or one
of the other attributes. That is, all of the attributes except BLINK, REVERSE,
and UNDERLINE are mutually exclusive.
Color and Monochrome Attributes
Support for the REVERSE and INVISIBLE attributes does not depend on the
color versus monochrome status of the monitor. On any monitor, for example,
specifying INVISIBLE inanATTRIBUTE clause prevents its 4GL statement from
displaying output on the screen, or else from echoing the users keystrokes
during data entry. (But the screen shows the character positions to which the
screen cursor moves while the user types.)
For other attributes, 4GL supports either color or monochrome monitors, but
not both. If you have a color monitor, you cannot display the monochrome
attributes (such as BOLD or DIM). If you have a monochrome monitor, you
cannot display the color attributes (such as RED or BLUE).
For all ATTRIBUTE clauses and eld attributes, the following table shows the
effects of the color attributes on a monochrome monitor, as well as the effects
of the intensity attributes on a color monitor.
If you specify the INVISIBLE attribute, 4GL does not display the data that the
user enters in the eld. The data value, however, is stored in the input buffer,
and is also available by using the get_dbuf( ) function.
Color Attribute Monochrome Display Intensity Attribute Color Display
WHITE
YELLOW
RED
MAGENTA
BLUE
GREEN
CYAN
BLACK
Normal
Bold
Bold
Bold
Dim
Dim
Dim
Dim
NORMAL
BOLD
DIM
White
Red
Blue
Data Types and Expressi ons 3-99
ATTRIBUTE Cl ause
The following example demonstrates using the ATTRIBUTE clause in an
ERROR statement. If the insert_items( ) function returns FALSE, 4GL rolls
back the changes to the database and displays the error message:
IF NOT insert_items( ) THEN
ROLLBACK WORK
ERROR "Unable to insert items."
ATTRIBUTE(RED, REVERSE, BLINK)
RETURN
END IF
If the terminal supports color, 4GL displays the error message in red,
blinking, reverse video. If the terminal screen is monochrome, 4GL displays
the error message in bold, blinking, reverse video.
Within its scope (which may be while a eld, a form, or a 4GL window is
displayed, or while a statement executes), a color attribute overrides any
default colors specied for your terminal. (The next page describes the prece-
dence of 4GL attributes.)
Precedence of Attributes
You can assign different attributes to the same eld. During execution of
eld-related statements, however, 4GL uses these rules of precedence
(descending) to resolve any conicts among attribute specications:
1. The ATTRIBUTE clause of the current statement.
2. The attributes fromthe eld descriptions in the ATTRIBUTES section
of the current form le. (See Field Attribute Syntax on page 6-34.)
3. The default attributes specied in the syscolatt table of any elds
linked to database columns. To modify the syscolatt table, use the
upscol utility. For information on using this utility, see Appendix B,
INFORMIX-4GL Utility Programs.
4. The ATTRIBUTE clause of the most recent OPTIONS statement.
5. The ATTRIBUTE clause of the current form in the most recent
DISPLAY FORM statement.
6. The ATTRIBUTE clause of the current 4GL windowin the most recent
OPEN WINDOW statement.
7. The default reserved line positions and the default foreground color
on your terminal.
3-100 INFORMIX- 4GL Reference Manual
ATTRIBUTE Cl ause
The eld-related statements of INFORMIX-4GL are these:
You cannot override the attributes specied for the ERROR, MESSAGE, and
PROMPT statements, so precedence rules do not affect these statements.
Keywords of an ATTRIBUTES clause produce their documented effects only
when the termcap or terminfo les and the physical terminals support the
attribute. For more information on these les, see Appendix F,
Modifying termcap and terminfo.
On UNIX systems that use terminfo les rather than termcap, 4GL does not
support attributes that specify colors, and the only valid keywords are
REVERSE and UNDERLINE.
Important: Some terminal entries in termcap or terminfo include the sg#1 or
xmc#1 capabilities. If you are using one of these terminals and if the attributes
specied for the INPUT ARRAY statement are different than the attributes of the
current formor window, 4GL replaces the right and left square brackets that indicate
the input elds with blank characters. 4GL uses the blank character as a transition
character between the different attributes.
References
CONSTRUCT, DATABASE, DISPLAY, DISPLAY ARRAY, DISPLAY FORM,
ERROR, INPUT, INPUT ARRAY, MESSAGE, OPENWINDOW, OPTIONS, PROMPT
CONSTRUCT
DISPLAY
DISPLAY ARRAY
DISPLAY FORM
INPUT
INPUT ARRAY
4
Chapter
INFORMIX-4GL Statements
In This Chapter . . . . . . . . . . . . . . . . . . . . 4-9
The 4GL Statement Set . . . . . . . . . . . . . . . . . 4-9
Types of SQL Statements . . . . . . . . . . . . . . . 4-10
Other Types of 4GL Statements . . . . . . . . . . . . . 4-13
Statement Descriptions . . . . . . . . . . . . . . . . . 4-15
CALL . . . . . . . . . . . . . . . . . . . . . . 4-16
Arguments . . . . . . . . . . . . . . . . . . . 4-17
The RETURNING Clause . . . . . . . . . . . . . . 4-19
Restrictions on Returned Character Strings . . . . . . . . 4-20
Invoking a Function Without CALL . . . . . . . . . . 4-21
CASE . . . . . . . . . . . . . . . . . . . . . . 4-22
The WHEN Blocks . . . . . . . . . . . . . . . . 4-23
The OTHERWISE Block . . . . . . . . . . . . . . 4-24
The EXIT CASE Statement and the END CASE Keywords . . 4-25
CLEAR . . . . . . . . . . . . . . . . . . . . . 4-28
The CLEAR FORM Option . . . . . . . . . . . . . 4-28
The CLEAR WINDOW Option . . . . . . . . . . . . 4-29
The CLEAR WINDOW SCREEN Option. . . . . . . . . 4-29
The CLEAR SCREEN Option. . . . . . . . . . . . . 4-29
The CLEAR Field Option . . . . . . . . . . . . . . 4-30
CLOSE FORM . . . . . . . . . . . . . . . . . . . 4-31
CLOSE WINDOW. . . . . . . . . . . . . . . . . . 4-33
CONSTRUCT . . . . . . . . . . . . . . . . . . . 4-35
The CONSTRUCT Variable Clause. . . . . . . . . . . 4-38
The ATTRIBUTE Clause . . . . . . . . . . . . . . 4-42
The HELP Clause. . . . . . . . . . . . . . . . . 4-44
The CONSTRUCT Input Control Blocks . . . . . . . . . 4-45
The NEXT FIELD Clause . . . . . . . . . . . . . . 4-53
The CONTINUE CONSTRUCT Statement . . . . . . . . 4-54
4-2 INFORMIX- 4GL Reference Manual
The EXIT CONSTRUCT Statement . . . . . . . . . . . 4-55
The END CONSTRUCT Keywords. . . . . . . . . . . 4-56
Using Built-In Functions and Operators . . . . . . . . . 4-56
Search Criteria for Query by Example . . . . . . . . . . 4-57
Positioning the Screen Cursor . . . . . . . . . . . . 4-62
Using WORDWRAP in CONSTRUCT. . . . . . . . . . 4-63
Editing During a CONSTRUCT Statement . . . . . . . . 4-64
Completing a Query . . . . . . . . . . . . . . . . 4-64
CONTINUE . . . . . . . . . . . . . . . . . . . . 4-68
CURRENT WINDOW . . . . . . . . . . . . . . . . 4-70
DATABASE . . . . . . . . . . . . . . . . . . . . 4-73
The Database Specication . . . . . . . . . . . . . 4-74
The Default Database at Compile Time . . . . . . . . . 4-75
The Current Database at Runtime . . . . . . . . . . . 4-76
The EXCLUSIVE Keyword . . . . . . . . . . . . . 4-77
Testing SQLCA.SQLAWARN. . . . . . . . . . . . . 4-78
Effects of the Default Database on Error Handling . . . . . 4-78
Additional Facts About Connections . . . . . . . . . . 4-79
DEFER . . . . . . . . . . . . . . . . . . . . . . 4-80
Interrupting Screen Interaction Statements . . . . . . . . 4-81
Interrupting SQL Statements . . . . . . . . . . . . . 4-82
DEFINE . . . . . . . . . . . . . . . . . . . . . 4-83
The Context of DEFINE Declarations . . . . . . . . . . 4-84
Indirect Typing . . . . . . . . . . . . . . . . . 4-85
Declaring the Names and Data Types of Variables . . . . . 4-87
Variables of Simple Data Types . . . . . . . . . . . . 4-88
Variables of Large Data Types . . . . . . . . . . . . 4-89
Variables of Structured Data Types . . . . . . . . . . . 4-89
DISPLAY . . . . . . . . . . . . . . . . . . . . . 4-93
Sending Output to the Line Mode Overlay . . . . . . . . 4-94
Sending Output to the Current 4GL Window . . . . . . . 4-95
Sending Output to a Screen Form . . . . . . . . . . . 4-99
The ATTRIBUTE Clause . . . . . . . . . . . . . . 4-102
Displaying Numeric and Monetary Values . . . . . . . . 4-103
Displaying Time Values. . . . . . . . . . . . . . . 4-104
DISPLAY ARRAY . . . . . . . . . . . . . . . . . . 4-105
The ATTRIBUTE Clause . . . . . . . . . . . . . . 4-107
The ON KEY Blocks . . . . . . . . . . . . . . . . 4-109
The EXIT DISPLAY Statement . . . . . . . . . . . . 4-111
The END DISPLAY Keywords . . . . . . . . . . . . 4-111
Using Built-In Functions and Operators . . . . . . . . . 4-112
INFORMIX- 4GL Statements 4-3
Scrolling During the DISPLAY ARRAY Statement . . . . . . 4-114
Completing the DISPLAY ARRAY Statement . . . . . . . . 4-114
DISPLAY FORM . . . . . . . . . . . . . . . . . . . 4-116
Form Attributes . . . . . . . . . . . . . . . . . . 4-116
Reserved Lines . . . . . . . . . . . . . . . . . . 4-117
END . . . . . . . . . . . . . . . . . . . . . . . 4-119
ERROR . . . . . . . . . . . . . . . . . . . . . . 4-121
The Error Line . . . . . . . . . . . . . . . . . . 4-121
The ATTRIBUTE Clause . . . . . . . . . . . . . . . 4-122
System Error Messages . . . . . . . . . . . . . . . 4-123
EXIT . . . . . . . . . . . . . . . . . . . . . . . 4-124
Leaving a Control Structure . . . . . . . . . . . . . . 4-124
Leaving a Function . . . . . . . . . . . . . . . . . 4-125
Leaving a Report . . . . . . . . . . . . . . . . . 4-125
Leaving the Program . . . . . . . . . . . . . . . . 4-126
FINISH REPORT . . . . . . . . . . . . . . . . . . . 4-128
FOR . . . . . . . . . . . . . . . . . . . . . . . 4-131
The TO Clause . . . . . . . . . . . . . . . . . . 4-131
The STEP Clause . . . . . . . . . . . . . . . . . 4-132
The CONTINUE FOR Statement . . . . . . . . . . . . 4-132
The EXIT FOR Statement . . . . . . . . . . . . . . . 4-133
The END FOR Keywords . . . . . . . . . . . . . . 4-133
Databases with Transactions . . . . . . . . . . . . . 4-133
FOREACH . . . . . . . . . . . . . . . . . . . . . 4-134
Cursor Names . . . . . . . . . . . . . . . . . . 4-136
The USING Clause . . . . . . . . . . . . . . . . . 4-137
The INTO Clause . . . . . . . . . . . . . . . . . 4-137
The WITH REOPTIMIZATION Keywords. . . . . . . . . 4-138
The FOREACH Statement Block . . . . . . . . . . . . 4-139
The END FOREACH Keywords . . . . . . . . . . . . 4-141
FUNCTION . . . . . . . . . . . . . . . . . . . . 4-143
The Prototype of the Function . . . . . . . . . . . . . 4-144
The FUNCTION Program Block . . . . . . . . . . . . 4-145
Data Type Declarations . . . . . . . . . . . . . . . 4-145
The Function as a Local Scope of Reference . . . . . . . . 4-146
Executable Statements. . . . . . . . . . . . . . . . 4-147
Returning Values to the Calling Routine . . . . . . . . . 4-147
The END FUNCTION Keywords . . . . . . . . . . . . 4-148
GLOBALS . . . . . . . . . . . . . . . . . . . . . 4-149
Declaring and Exporting Global Variables . . . . . . . . . 4-150
Importing Global Variables . . . . . . . . . . . . . . 4-151
4-4 INFORMIX- 4GL Reference Manual
GOTO . . . . . . . . . . . . . . . . . . . . . . 4-155
IF. . . . . . . . . . . . . . . . . . . . . . . . 4-158
INITIALIZE . . . . . . . . . . . . . . . . . . . . 4-160
The LIKE Clause . . . . . . . . . . . . . . . . . 4-161
INPUT . . . . . . . . . . . . . . . . . . . . . . 4-164
The Binding Clause . . . . . . . . . . . . . . . . 4-166
The ATTRIBUTE Clause . . . . . . . . . . . . . . 4-170
The HELP Clause . . . . . . . . . . . . . . . . . 4-170
The INPUT Control Block . . . . . . . . . . . . . . 4-171
The CONTINUE INPUT Statement. . . . . . . . . . . 4-181
The EXIT INPUT Statement . . . . . . . . . . . . . 4-181
The END INPUT Keywords . . . . . . . . . . . . . 4-182
Using Built-In Functions and Operators . . . . . . . . . 4-182
Keyboard Interaction . . . . . . . . . . . . . . . 4-183
Cursor Movement in Simple Fields. . . . . . . . . . . 4-184
Multiple-Segment Fields . . . . . . . . . . . . . . 4-185
Using Large Data Types . . . . . . . . . . . . . . 4-188
Completing the INPUT Statement . . . . . . . . . . . 4-188
INPUT ARRAY . . . . . . . . . . . . . . . . . . . 4-190
The Binding Clause . . . . . . . . . . . . . . . . 4-192
The ATTRIBUTE Clause . . . . . . . . . . . . . . 4-194
The HELP Clause . . . . . . . . . . . . . . . . . 4-199
The INPUT ARRAY Input Control Blocks . . . . . . . . 4-200
The CONTINUE INPUT Statement. . . . . . . . . . . 4-217
The EXIT INPUT Statement . . . . . . . . . . . . . 4-218
The END INPUT Keywords . . . . . . . . . . . . . 4-218
Using Built-In Functions and Operators . . . . . . . . . 4-218
Using Large Data Types . . . . . . . . . . . . . . 4-221
Keyboard Interaction . . . . . . . . . . . . . . . 4-221
Completing the INPUT ARRAY Statement . . . . . . . . 4-224
LABEL . . . . . . . . . . . . . . . . . . . . . . 4-227
LET . . . . . . . . . . . . . . . . . . . . . . . 4-229
LOAD . . . . . . . . . . . . . . . . . . . . . . 4-233
The Input File . . . . . . . . . . . . . . . . . . 4-234
The DELIMITER Clause . . . . . . . . . . . . . . 4-236
The INSERT Clause . . . . . . . . . . . . . . . . 4-237
Performance Issues with LOAD. . . . . . . . . . . . 4-240
LOCATE . . . . . . . . . . . . . . . . . . . . . 4-242
The List of Large Variables . . . . . . . . . . . . . 4-243
The IN MEMORY Option . . . . . . . . . . . . . . 4-244
The IN FILE Option . . . . . . . . . . . . . . . . 4-244
INFORMIX- 4GL Statements 4-5
Passing Large Variables to Functions . . . . . . . . . . 4-245
Freeing the Storage Allocated to a Large Data Type . . . . . 4-246
MAIN . . . . . . . . . . . . . . . . . . . . . . 4-247
Variables Declared in the MAIN Statement . . . . . . . . 4-248
MENU . . . . . . . . . . . . . . . . . . . . . . 4-250
The MENU Control Blocks . . . . . . . . . . . . . . 4-252
Invisible Menu Options . . . . . . . . . . . . . . . 4-259
The CONTINUE MENU Statement . . . . . . . . . . . 4-261
The EXIT MENU Statement . . . . . . . . . . . . . . 4-261
The NEXT OPTION Clause . . . . . . . . . . . . . . 4-262
The HIDE OPTION and SHOW OPTION Keywords . . . . . 4-263
Nested MENU Statements . . . . . . . . . . . . . . 4-265
The END MENU Keywords. . . . . . . . . . . . . . 4-265
Identiers in the MENU Statement . . . . . . . . . . . 4-265
Choosing a Menu Option . . . . . . . . . . . . . . 4-267
Scrolling the Menu Options . . . . . . . . . . . . . . 4-268
Completing the MENU Statement . . . . . . . . . . . 4-270
COMMAND KEY Conicts . . . . . . . . . . . . . . 4-272
MESSAGE . . . . . . . . . . . . . . . . . . . . . 4-275
The Message Line . . . . . . . . . . . . . . . . . 4-275
The ATTRIBUTE Clause . . . . . . . . . . . . . . . 4-276
NEED. . . . . . . . . . . . . . . . . . . . . . . 4-278
OPEN FORM . . . . . . . . . . . . . . . . . . . . 4-279
Specifying a Filename . . . . . . . . . . . . . . . . 4-279
The Form Name . . . . . . . . . . . . . . . . . . 4-280
Displaying a Form in a 4GL Window . . . . . . . . . . 4-280
OPEN WINDOW. . . . . . . . . . . . . . . . . . . 4-281
The 4GL Window Stack . . . . . . . . . . . . . . . 4-282
The AT Clause . . . . . . . . . . . . . . . . . . 4-282
The WITH ROWS, COLUMNS Clause . . . . . . . . . . 4-283
The WITH FORM Clause. . . . . . . . . . . . . . . 4-284
The OPEN WINDOW ATTRIBUTE Clause . . . . . . . . 4-285
OPTIONS . . . . . . . . . . . . . . . . . . . . . 4-293
Features Controlled by OPTIONS Clauses . . . . . . . . . 4-294
Positioning Reserved Lines . . . . . . . . . . . . . . 4-297
Cursor Movement in Interactive Statements . . . . . . . . 4-298
The OPTIONS ATTRIBUTE Clause . . . . . . . . . . . 4-299
The HELP FILE Option . . . . . . . . . . . . . . . 4-301
Assigning Logical Keys . . . . . . . . . . . . . . . 4-301
Interrupting SQL Statements . . . . . . . . . . . . . 4-303
Setting Default Screen Modes . . . . . . . . . . . . . 4-309
4-6 INFORMIX- 4GL Reference Manual
OUTPUT TO REPORT . . . . . . . . . . . . . . . . 4-310
PAUSE . . . . . . . . . . . . . . . . . . . . . . 4-313
PREPARE . . . . . . . . . . . . . . . . . . . . . 4-314
Statement Identier . . . . . . . . . . . . . . . . 4-315
Statement Text . . . . . . . . . . . . . . . . . . 4-316
Statements That Can or Must Be Prepared . . . . . . . . 4-317
Statements That Cannot Be Prepared . . . . . . . . . . 4-319
Using Parameters in Prepared Statements . . . . . . . . 4-321
Preparing Statements with SQL Identiers . . . . . . . . 4-322
Preparing Sequences of Multiple SQL Statements. . . . . . 4-323
Runtime Errors in Multistatement Texts . . . . . . . . . 4-324
Using Prepared Statements for Efciency . . . . . . . . 4-325
PRINT . . . . . . . . . . . . . . . . . . . . . . 4-326
PROMPT . . . . . . . . . . . . . . . . . . . . . 4-327
The PROMPT String . . . . . . . . . . . . . . . . 4-328
The Response Variable . . . . . . . . . . . . . . . 4-329
The FOR Clause . . . . . . . . . . . . . . . . . 4-329
The ATTRIBUTE Clauses . . . . . . . . . . . . . . 4-329
The HELP Clause . . . . . . . . . . . . . . . . . 4-331
The ON KEY Blocks . . . . . . . . . . . . . . . . 4-331
The END PROMPT Keywords . . . . . . . . . . . . 4-333
REPORT . . . . . . . . . . . . . . . . . . . . . 4-334
The Report Prototype . . . . . . . . . . . . . . . 4-335
The Report Program Block. . . . . . . . . . . . . . 4-336
Two-Pass Reports . . . . . . . . . . . . . . . . . 4-336
The Exit Report Statement . . . . . . . . . . . . . . 4-337
The END REPORT Keywords . . . . . . . . . . . . 4-338
RETURN . . . . . . . . . . . . . . . . . . . . . 4-339
The Data Types of Returned Values . . . . . . . . . . 4-340
RUN . . . . . . . . . . . . . . . . . . . . . . 4-342
Screen Display Modes . . . . . . . . . . . . . . . 4-343
The RETURNING Clause . . . . . . . . . . . . . . 4-343
The WITHOUT WAITING Clause . . . . . . . . . . . 4-345
SCROLL . . . . . . . . . . . . . . . . . . . . . 4-346
SKIP. . . . . . . . . . . . . . . . . . . . . . . 4-348
SLEEP . . . . . . . . . . . . . . . . . . . . . . 4-350
SQL . . . . . . . . . . . . . . . . . . . . . . . 4-351
START REPORT . . . . . . . . . . . . . . . . . . 4-356
The TO Clause . . . . . . . . . . . . . . . . . . 4-357
Dynamic Output Conguration . . . . . . . . . . . . 4-358
INFORMIX- 4GL Statements 4-7
TERMINATE REPORT . . . . . . . . . . . . . . . . . 4-365
UNLOAD . . . . . . . . . . . . . . . . . . . . . 4-368
The Output File . . . . . . . . . . . . . . . . . . 4-369
The DELIMITER Clause . . . . . . . . . . . . . . . 4-370
Host Variables . . . . . . . . . . . . . . . . . . 4-371
The Backslash Escape Character . . . . . . . . . . . . 4-372
VALIDATE . . . . . . . . . . . . . . . . . . . . . 4-373
The LIKE Clause . . . . . . . . . . . . . . . . . 4-374
The syscolval Table. . . . . . . . . . . . . . . . . 4-375
WHENEVER . . . . . . . . . . . . . . . . . . . . 4-377
The Scope of the WHENEVER Statement . . . . . . . . . 4-378
The ERROR Condition . . . . . . . . . . . . . . . 4-379
The ANY ERROR Condition . . . . . . . . . . . . . 4-379
The NOT FOUND Condition . . . . . . . . . . . . . 4-380
The WARNING Condition . . . . . . . . . . . . . . 4-380
The GOTO Option . . . . . . . . . . . . . . . . . 4-380
The CALL Option . . . . . . . . . . . . . . . . . 4-381
The CONTINUE Option . . . . . . . . . . . . . . . 4-382
The STOP Option . . . . . . . . . . . . . . . . . 4-382
WHILE . . . . . . . . . . . . . . . . . . . . . . 4-383
The CONTINUE WHILE Statement . . . . . . . . . . . 4-384
The EXIT WHILE Statement . . . . . . . . . . . . . 4-384
The END WHILE Keywords . . . . . . . . . . . . . 4-384
4-8 INFORMIX- 4GL Reference Manual
INFORMIX- 4GL Statements 4-9
In This Chapter
This chapter describes the INFORMIX-4GL statements, classifying them by
functional category and also providing alphabetized descriptions of the
individual statements of 4GL that are not SQL statements.
The 4GL Statement Set
4GL supports the SQL language, but it is sometimes convenient to distinguish
between SQL statements and other 4GL statement, as follows:
B SQL statements operate on tables and their columns in a database.
B 4GL statements operate on variables in memory.
4-10 INFORMIX- 4GL Reference Manual
Types of SQL Statements
Types of SQL Statements
SQL statements of 4GL can be classied among these functional categories:
B Data denition statements
B Cursor manipulation statements
B Data manipulation statements
B Dynamic management statements
B Query optimization statements
B Data access statements
B Data integrity statements
B Stored procedure statements
B Optical statements
The SQL statements in each of these categories are listed in sections that
follow. SQL statements that are not listed here are not available in 4GL.
For syntax and usage information about SQL statements, see the Informix
Guide to SQL: Syntax. To use the SQL statements identied by the icon
in a 4GL program, you must either put the statement in an SQL block, as
described in SQL on page 4-351, or else prepare the statement, as described
in PREPARE on page 4-314.
You must also prepare (or delimit with SQLEND SQL) any other SQL state-
ments that specify syntax that was not supported by Informix 4.1 database
servers. SQL statements that include only Informix 4.1 syntax can be directly
embedded or delimited with SQLEND SQL, but most SQL statements can
also be prepared and can appear in SQL blocks.
SQL
INFORMIX- 4GL Statements 4-11
Types of SQL Statements
SQL Data Denition Statements
SQL Cursor Manipulation Statements
SQL Data Manipulation Statements
SQL Dynamic Management Statements
ALTER FRAGMENT CREATE VIEW
ALTER INDEX DATABASE
ALTER TABLE DROP DATABASE
CLOSE DATABASE DROP INDEX
CREATE DATABASE DROP PROCEDURE
CREATE EXTERNAL TABLE DROP ROLE
CREATE INDEX DROP SYNONYM
CREATE PROCEDURE FROM DROP TABLE
CREATE ROLE DROP TRIGGER
CREATE SCHEMA DROP VIEW
CREATE SYNONYM RENAME COLUMN
CREATE TABLE RENAME DATABASE
CREATE TRIGGER RENAME TABLE
CLOSE FREE
DECLARE OPEN
FETCH PUT
FLUSH SET AUTOFREE
INSERT SELECT
DELETE UNLOAD
LOAD UPDATE
OUTPUT
EXECUTE PREPARE
EXECUTE IMMEDIATE SET DEFERRED_PREPARE
FREE
SQL
SQL SQL
SQL SQL
SQL
SQL
SQL
SQL
SQL
SQL
4-12 INFORMIX- 4GL Reference Manual
Types of SQL Statements
SQL Query Optimization Statements
SQL Data Access Statements
SQL Data Integrity Statements
SQL Stored Procedure Statements
SQL Optical Subsystems Statements
Optical statements are only valid on Informix database servers that support
optical storage; no INFORMIX-SE database server, for example, supports these
features.
SET EXPLAIN SET RESIDENCY
SET OPTIMIZATION SET SCHEDULE LEVEL
SET PDQPRIORITY UPDATE STATISTICS
GRANT SET LOCK MODE
GRANT FRAGMENT SET ROLE
LOCK TABLE SET SESSION
REVOKE SET TRANSACTION
REVOKE FRAGMENT UNLOCK TABLE
SET ISOLATION
BEGIN WORK SET PLOAD FILE
COMMIT WORK SET TRANSACTION MODE
ROLLBACK WORK START VIOLATIONS TABLE
SET DATABASE OBJECT MODE STOP VIOLATIONS TABLE
SET LOG WHENEVER
EXECUTE PROCEDURE SET DEBUG FILE TO
ALTER OPTICAL CLUSTER RELEASE
CREATE OPTICAL CLUSTER RESERVE
DROP OPTICAL CLUSTER SET MOUNTING TIMING
SQL
SQL SQL
SQL
SQL SQL
SQL
SQL
SQL
SQL
SQL
SQL
SQL SQL
SQL
SQL SQL
SQL SQL
SQL SQL
SQL SQL
INFORMIX- 4GL Statements 4-13
Other Types of 4GL Statements
Other Types of 4GL Statements
Six other types of 4GL statements are available. (These are sometimes called
simply 4GL statements, to distinguish them fromSQL statements.)
B Denition and declaration statements
B Storage manipulation statements
B Program ow control statements
B Compiler directives
B Screen interaction statements
B Report execution statements
4GL Denition and Declaration Statements
4GL Storage Manipulation Statements
4GL Program Flow Control Statements
DEFINE LABEL
FUNCTION MAIN
GLOBALSEND GLOBALS REPORT
CLOSE FORM LET
FREE LOCATE
INITIALIZE VALIDATE
CALL GOTO
CASE IF
CONTINUE OUTPUT TO REPORT
DATABASE RETURN
END RUN
EXIT START REPORT
FINISH REPORT TERMINATE REPORT
FOR WHILE
FOREACH
4-14 INFORMIX- 4GL Reference Manual
Other Types of 4GL Statements
4GL Compiler Directives
4GL Screen Interaction Statements
4GL Report Execution Statements
Most 4GL statements are not sensitive to whether INFORMIX-SE or Informix
Dynamic Server supports the application. INFORMIX-SE cannot store values
in BYTE, TEXT, or VARCHAR columns, but any 4GL program can declare
variables of these data types.
DEFER SQLEND SQL
GLOBALS lename WHENEVER
CLEAR INPUT ARRAY
CLOSE WINDOW MENU
CONSTRUCT MESSAGE
COPY ARRAY OPEN FORM
CURRENT WINDOW OPEN WINDOW
DISPLAY OPTIONS
DISPLAY ARRAY PROMPT
DISPLAY FORM REMOVE ARRAY
ERROR SCROLL
INPUT SLEEP
NEED PRINT
PAUSE SKIP
INFORMIX- 4GL Statements 4-15
Statement Descri pti ons
Statement Descriptions
The following sections describe the 4GL statements that are not SQL state-
ments, and certain SQL statements. Each description includes these elements:
B The name and a terse summary of the effect of the 4GL statement
B A syntax diagram
B Notes on usage, typically arranged by syntax elements
If a description is longer than a fewpages, a bulleted list identies the major
topical headings and their page numbers.
A list of related statements concludes most of these statement descriptions.
CALL
4-16 INFORMIX- 4GL Reference Manual
CALL
The CALL statement invokes a specied function.
Usage
CALL can invoke the following types of functions from a 4GL application:
B Programmer-dened 4GL functions
B 4GL built-in functions
B C language functions
It can also invoke ESQL/C functions. Programmer-dened 4GL functions are
dened in FUNCTION statements. These functions can appear in the same
source le as the MAIN statement, or they can be compiled in separate .4gl
modules (individually, or with other function and report denitions) and
linked later to the MAIN program block.
When 4GL encounters a CALL statement at runtime, it locates the specied
FUNCTION program block and executes its statements in sequence. If the
function is not a built-in function, a link-time error occurs unless exactly one
denition of that function exists in the modules that make up the program.
The programblock containing the CALL statement is calledthe calling routine.
The RETURNING clause can specify the name of one or more variables that
function returns to the calling routine. This variable (or list of variables) has
the same syntax as a receiving variable in the LET statement.
Element Description
function is the identier of the function to be invoked.
,
)
,
RETURNING
CALL function
Receiving
Variable
p. 4-229
)
4GL Expression
p. 3-49
INFORMIX- 4GL Statements 4-17
CALL
Tip: Unlike 4GL identiers, the names of C functions are case sensitive and must
typically appear in lowercase letters within the function call. For more information,
see Appendix C, Using C with INFORMIX-4GL.
In this example, the CALL statement invokes the show_menu( ) function:
MAIN
...
CALL show_menu()
...
END MAIN
FUNCTION show_menu()
...
END FUNCTION
Chapter 5, Built-In Functions and Operators, provides more information
about functions. The following sections describe these topics:
B Arguments on page 4-17
B The RETURNING Clause on page 4-19
B Restrictions on Returned Character Strings on page 4-20
B Invoking a Function Without CALL on page 4-21
Arguments
The argument list after the function name species values for CALL to pass
as actual arguments to the function. These actual arguments can be any 4GL
expression (as described in Expressions of 4GL on page 3-49) if the
returned data types are compatible with the corresponding formal arguments
in the FUNCTION denition. Statements in the FUNCTION denition are
executed with the values of actual arguments substituted for the corre-
sponding formal arguments. (Parentheses are always required around the
list of argument, even if the list is empty because the function accepts no
arguments.)
4-18 INFORMIX- 4GL Reference Manual
CALL
For example, the following program fragment passes the current values of
p_customer.fname and p_customer.lname to the print_name( ) function:
MAIN
...
CALL print_name(p_customer.fname, p_customer.lname)
...
END MAIN
FUNCTION print_name(fname, lname)
DEFINE fname, lname CHAR(15)
...
END FUNCTION
When passing arguments to a function, keep these considerations in mind:
B Values in the argument list must correspond in number and position
(within the list) to the formal arguments that were specied in the
FUNCTION statement.
B Data types of values must be compatible, but need not be identical,
to those of the formal arguments in the FUNCTION statement.
B An argument can be an expression that contains variables of simple
data types, or simple members of records, or simple elements of
arrays. An argument can also be a BYTE or TEXT variable.
B Results can be unpredictable if a variable that has not yet been
assigned a value is used as an argument in a CALL statement.
Passing Arguments by Value
How4GL passes an argument between the calling routine and the function
depends on the data type of the argument. Except for variables of data type
BYTE or TEXT, arguments are passed to the function by value. That is, a copy
of the argument is passed. (In this case, changing the value of a formal
argument within the function has no effect in the calling routine.)
Passing Arguments by Reference
4GL passes arguments of data type BYTE and TEXT by reference. In this case,
the function works directly with the actual variable, rather than with a copy.
That is, changing a reference to a formal argument in a function changes the
corresponding variable in the calling routine. You can use this as a substitute
for the RETURNING clause, which does not permit BYTE or TEXT variables.
INFORMIX- 4GL Statements 4-19
CALL
This example shows howto pass a BYTE or TEXT argument to a 4GL function:
MAIN
DEFINE resume TEXT
...
LOCATE resume IN MEMORY
CALL get_resume(resume)
END MAIN
FUNCTION get_resume(parm)
DEFINE parm TEXT
...
END FUNCTION
In this example, the LOCATE statement allocates memory for the TEXT
variable, and places a pointer to this variable in resume. Any change to parm
within the get_resume( ) function also changes the TEXT variable in MAIN.
The RETURNING Clause
The RETURNING clause assigns values returned by the function to variables
in the calling routine. To use this feature, you must do the following:
B Determine howmany values function returns. In the CALL statement,
specify that number of variables in the RETURNING clause.
B If you write the function denition, include expressions in a RETURN
statement to specify values returned by the function. (For more infor-
mation, see RETURN on page 4-339.)
When returning values to the CALL statement, keep the following consider-
ations in mind:
B The values in the RETURN statement of the FUNCTION denition
must correspond in number and position to the variables specied in
the RETURNING clause of the CALL statement. Data types of the
RETURNING variables must be compatible with the RETURN values,
but they neednot be identical. (For more information, see Summary
of Compatible 4GL Data Types on page 3-45.)
B It is an error to specify more variables in the RETURNINGclause than
the number of values in the RETURN statement of the FUNCTION
denition. (If the RETURNING clause species fewer variables, any
additional returned values are ignored by the calling routine.)
4-20 INFORMIX- 4GL Reference Manual
CALL
B You can return simple or RECORD variables from a function. You
cannot, however, return RECORD members of ARRAY, BYTE, and
TEXT data types.
B The RETURNING clause passes information by value. Because
variables of the BYTE and TEXT data types are passed by reference,
they cannot be included in the RETURNING clause. (For more infor-
mation, see Passing Arguments by Reference on page 4-18.)
Important: It is an error to specify a RETURNING clause in the CALL statement if
the function does not return anything. It is not an error to omit the RETURNING
clause when you invoke a function that returns values if no statement in the calling
routine references the returned values.
In the next example, the get_cust( ) function returns values of whole_price
and ret_price to the CALL statement. 4GL then assigns the whole_price and
ret_price variables to the wholesale and retail variables in the price record:
MAIN
DEFINE price RECORD
wholesale, retail MONEY
END RECORD
...
CALL get_cust() RETURNING price.*
...
END MAIN
FUNCTION get_cust()
DEFINE whole_price, ret_price MONEY
...
RETURN whole_price, ret_price
END FUNCTION
Restrictions on Returned Character Strings
Areturned value that a CHAR variable receives cannot be longer than 32,767
bytes. (Earlier releases of 4GL allocated 5 kilobytes of memory to store
character strings returned by functions, in 10 blocks of 512 bytes, but this
restriction has been replaced in current releases by the 32,767 byte limit.)
You can also use TEXT variables to pass longer character values by reference,
rather than using the RETURNING clause.
INFORMIX- 4GL Statements 4-21
CALL
Invoking a Function Without CALL
If a function returns a value, you can invoke it without using CALL by simply
including it (and any arguments) within an expression in contexts where the
returned value is valid. In the following example, the value returned by a
function call appears in an IF statement as a Boolean expression, and a LET
statement uses a function call as an operand within an arithmetic expression:
IF get_order() THEN
LET total = total + get_items()
END IF
For more information, see Function Calls as Operands on page 3-58.
The Comma and Double-Pipe Symbols
As the syntax diagram for CALL on page 4-16 indicates, if a function has
more than one actual argument, a comma ( , ) symbol is required between
successive arguments in the argument list.
The concatenation operator ( || ) can appear within character expressions in
the argument list, combining two operands (of any simple data type) as all or
part of a single argument to the function. The following example calls the
vitamin( ) function, which takes two character expressions as its arguments:
CALL vitamin(var1 || "A", "E") RETURNING varB[2]
This use of the concatenation operator is valid in calls to functions, regardless
of whether the CALL statement or an expression invokes the function.
Unlike in the LET statement, the comma and the concatenation operator are
not interchangeable in the argument list of a function call. In this context,
comma is the required separator and has no concatenation semantics.
References
DEFINE, FUNCTION, RETURN, WHENEVER
4-22 INFORMIX- 4GL Reference Manual
CASE
CASE
The CASE statement species statement blocks to be executed conditionally,
depending onthe value of an expression. Unlike IF statements, CASE does not
restrict the logical ow of control to only two branches.
Usage
The CASE statement is equivalent to a set of nested IF statements. You can
specify two types of CASE statements:
B If an expression follows the CASE keyword, you must specify INT,
SMALLINT, DECIMAL, CHAR(1), or VARCHAR(1) expressions in the
WHEN block. (The syntax diagramindicates a subset of general 4GL
expressions because of these data type restrictions.) 4GL executes the
statement block if both expressions return the same non-NULL value.
B If no expression follows the CASE keyword, the WHEN block must
specify a Boolean expression; if this returns TRUE, the WHENblock is
executed. (See Boolean Expressions on page 3-60.) This form of
CASE typically executes more quickly than the other.
Case II: (mul ti pl e cri teri a)
Case I: (si ngl e cri teri on)
statement WHEN
EXIT CASE
Boolean
Expression
p. 3-60
EXIT CASE
( )
WHEN
4GL
Expression
(subset)
p. 3-49
4GL
Expression
(subset)
p. 3-49
END CASE
OTHERWISE
Block
p. 4-24
CASE
statement
Element Description
statement is an SQL statement or other 4GL statement.
INFORMIX- 4GL Statements 4-23
CASE
There is an implicit EXIT CASE statement at the end of each WHEN block of
statements. An implicit or explicit EXIT CASE statement transfers program
control to the statement that immediately follows the END CASE keywords.
The WHEN Blocks
Each WHEN block species an expression and a block of one or more
associated statements. The WHEN block has the following syntax.
What data type can be returned by expression depends on what follows the
CASE keyword. If CASE (expression) precedes the rst WHEN block as a
single criterion, an INTEGER, SMALLINT, DECIMAL, CHAR(1), or VARCHAR(1)
expression must follow the WHEN keyword, returning a data type that
is compatible with the (expression) term after CASE. If a WHEN expression
matches the value of CASE (expression), 4GL executes the statements and
exits from the CASE statement. In the following example, both
customer_num and the WHEN expression values are of data type SMALLINT:
CASE (p_customer.customer_num)
WHEN 101
...
WHEN 102
...
END CASE
Element Description
statement is an SQL statement or other 4GL statement.
statement
WHEN Block
EXIT CASE
Boolean Expression
p. 3-60
4GL Expression
(subset) p. 3-49
WHEN
Case II: (mul ti pl e cri teri a)
WHEN
Case I: (si ngl e cri teri on)
4-24 INFORMIX- 4GL Reference Manual
CASE
If no (expression) term follows CASE, 4GL treats expression as a Boolean
(returning TRUE or FALSE) in each of the WHEN blocks. If this Boolean
expression returns TRUE (that is, neither zero nor NULL), 4GL executes the
corresponding block of statements, as in the following CASE statement:
CASE
WHEN total_price < 1000
...
WHEN total_price = 1000
...
WHEN total_price > 1000
...
END CASE
When more than one WHEN clause can satisfy your criteria, only the rst of
these causes its statement block to be executed. In these cases, the lexical
order of the WHEN clauses in effect prioritizes your logical criteria.
4GL does not execute the statement block if the expression in the WHENblock
returns FALSE or NULL, or if CASE expression returns NULL. (The IF and
WHILE statements and the WHERE clause of a COLOR attribute also treat any
NULL value returned from a 4GL Boolean expression as FALSE.)
The OTHERWISE Block
The OTHERWISE keyword species statements to be executed when 4GL does
not nd a matching WHEN block to execute. It has this syntax.
Element Description
statement is an SQL statement or other 4GL statement.
statement
OTHERWISE
OTHERWISE
Block
EXIT CASE
INFORMIX- 4GL Statements 4-25
CASE
4GL executes the OTHERWISE block only if it cannot execute any of the WHEN
blocks. If you include the OTHERWISE block, it must follow the last WHEN
block. In the next example, if neither 4GL Boolean expression in the WHEN
blocks returns TRUE, 4GL invokes the retry( ) function:
WHILE question ...
CASE
WHEN answer MATCHES "[Yy]"
CALL process()
LET question = FALSE
WHEN answer MATCHES "[Nn]"
CALL abort()
OTHERWISE
CALL retry()
END CASE
END WHILE
An implied EXIT CASE statement follows the OTHERWISE statement block.
Unless the OTHERWISE block contains a valid GOTO statement, program
control passes to the statement that follows the END CASE statement. But the
use of GOTO to leave a WHEN block, rather than an implicit or explicit EXIT
CASE statement, can cause runtime error -4518, as described in the next
section.
The EXIT CASE Statement and the END CASE Keywords
The EXIT CASE statement terminates processing of the WHENor OTHERWISE
block. When it executes an EXIT CASE statement, 4GL skips any statements
between EXIT CASE and the END CASE keywords and resumes execution at
the rst statement following the END CASE keywords.
The ENDCASE keywords indicate the end of the CASE statement. They must
follow either the last WHEN block or else the OTHERWISE block. In the next
example, quantity has a SMALLINT value. When quantity equals min_qty,
4GL executes the statement in the min_qty block. When quantity equals
max_qty, 4GL executes the statements in the max_qty block.
CASE (quantity)
WHEN min_qty
...
WHEN max_qty
...
END CASE
4-26 INFORMIX- 4GL Reference Manual
CASE
In the following example, print_option is a CHAR(1) variable that determines
the destination of output from a REPORT program block:
CASE (print_option)
WHEN "f"
PROMPT " Enter file names 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
Because WHEN blocks are logically disjunct, exactly one of the START
REPORT statements is executed within the CASE statement in this example.
Improper Use of Boolean Expressions with CASE
The 4GL compiler generally cannot detect the following improper syntax.
statement WHEN
EXIT CASE
( )
4GL
Expression
(subset)
p. 3-49
Boolean
Expression
p. 3-60
END CASE
OTHERWISE
Block
p. 4-24
CASE
INFORMIX- 4GL Statements 4-27
CASE
This is not valid because the expression that follows the WHEN keyword
must return a value of data type INT, SMALLINT, DECIMAL, CHAR(1), or
VARCHAR(1). Substituting a Boolean expression in this context tends to
produce unexpected runtime results. Boolean expressions are valid only in
Case II (multiple logical criteria).
For example, CASE statements with WHEN clauses of the following form
produce a false result.
To produce the intended result when the appropriate action depends on the
value in the WHEN clause, omit the expression that immediately follows the
CASE keyword. Use simplied logic, as in the following code, typically by
associating each WHEN expression value with a function call:
CASE variable
WHEN "A"
...
WHEN "B"
...
References
FOR, IF, WHILE
CASE Statement Translates to:
CASE variable WHEN A OR B if (variable == (A or B))
CASE variable
WHEN (variable = A OR variable = B)
if (variable == (variable == A
or variable == B))
4-28 INFORMIX- 4GL Reference Manual
CLEAR
CLEAR
The CLEAR statement can clear any of these portions of the screen display:
B The 4GL screen (excluding any open 4GL windows within it)
B Any specied 4GL window
B All of the elds in the current screen form
B A list of one or more specied elds in the current screen form
Usage
The CLEAR statement clears the specied portion of the display. It does not
change the value of any 4GL variable.
The CLEAR FORM Option
Use CLEAR FORM to clear all elds of the form in the current 4GL window:
CLEAR FORM
The CLEAR FORM option has no effect on other parts of the screen display.
Element Description
window is the name of the 4GL window to be cleared.
Field Clause
p. 3-87
CLEAR
SCREEN
FORM
,
window WINDOW
INFORMIX- 4GL Statements 4-29
CLEAR
The CLEAR WINDOW Option
Use CLEAR WINDOWwindowto clear a specied 4GL window, where window
is a 4GL identier that was declared in an OPEN WINDOW statement:
CLEAR WINDOW threshold
If the windowthat you specify has a border, the CLEAR WINDOWstatement
does not erase the border. You can specify any 4GL window, including one
that is not the current window, but the CLEAR WINDOW statement does not
affect which 4GL window is the current 4GL window in the window stack.
The CLEAR WINDOW SCREEN Option
If you specify CLEAR WINDOWSCREEN, 4GL takes the following actions:
B Clears the 4GL screen, except for the area occupied by any open 4GL
windows
B Leaves any information in the open 4GL windows untouched
B Does not change the current 4GL window setting
As in several other 4GL statements, the keyword SCREEN here species the
4GL screen.
The CLEAR SCREEN Option
Use the CLEAR SCREEN option to make the 4GL screen the current 4GL
window and to clear everything on it, including the Prompt, Message, and
Error lines. In the next example, choosing the Exit option clears the screen
and terminates the MENU statement:
MENU "ORDERS"
COMMAND "Add-order"
"Enter new order into database and print invoice"
HELP 301
CALL add_order( )
...
COMMAND "Exit"
"Return to MAIN MENU"
HELP 305
CLEAR SCREEN
EXIT MENU
END MENU
4-30 INFORMIX- 4GL Reference Manual
CLEAR
The CLEAR Field Option
Use the CLEAR eld option to clear the specied eld or elds in a form that
the current 4GL windowdisplays. For the syntax of the eldclause, see Field
Clause on page 3-87. The next example clears the elds named fname,
lname, address1, city, state, and zipcode:
CLEAR fname, lname, address1, city, state, zipcode
If you specify table.* (where table is a name or alias fromthe TABLE section of
the form specication le), CLEAR clears all the elds associated with
columns of that table. (See INSTRUCTIONS Section on page 6-74 for a
description of screen records and screen arrays that the record.* notation can
reference.)
For example, the following programfragment clears the orders screen record
and the rst four records of the s_items screen array:
FOREACH order_list INTO p_orders.*
CLEAR s_orders
FOR idx = 1 TO 4
CLEAR s_items[idx].*
END FOR
DISPLAY p_orders.* TO orders.*
...
END FOREACH
If a screen formis in the current 4GL window, the following statement clears
all the screen elds that are not associated with database columns:
CLEAR FORMONLY.*
Any elds that you associated with database columns in the ATTRIBUTES
section of the form specication le are not affected by this statement.
References
CLOSE FORM, CLOSE WINDOW, CURRENT WINDOW, DISPLAY, DISPLAY
ARRAY, INPUT, INPUT ARRAY, OPEN FORM, OPEN WINDOW, OPTIONS
INFORMIX- 4GL Statements 4-31
CLOSE FORM
CLOSE FORM
The CLOSE FORM statement releases the memory required for a form.
Usage
When it executes the OPEN FORM statement, 4GL loads the compiled screen
forminto memory. Until you close the form, it remains in memory. To regain
the memory allocated to a form, you can use the CLOSE FORMstatement. For
example, the following program fragment opens and displays the o_cust
form and then closes both the form and the 4GL window cust_w:
OPEN WINDOW cust_w AT 3,5 WITH 19 ROWS, 72 COLUMNS
OPEN FORM o_cust FROM "custform"
DISPLAY FORM o_cust ATTRIBUTE(MAGENTA)
...
CLOSE FORM o_cust
CLOSE WINDOW cust_w
If you open the formby using the WITH FORMoption of the OPEN WINDOW
statement, you do not need to use the CLOSE FORMstatement before closing
the 4GL window. In this case, CLOSE WINDOWboth closes the form(releasing
the memory allocated to that form) and closes the 4GL window(releasing the
memory allocated to that 4GL window).
CLOSE FORMaffects memory use only, not the logic of the 4GL program. After
you use CLOSE FORMto release the memory that supports a form, its name is
no longer associated with the form. If you subsequently try to redisplay the
form, an error message results. If you execute a newOPEN FORM or OPEN
WINDOW statement that species the same formname that an OPEN FORM
or OPENWINDOWstatement referenced previously, 4GL automatically closes
the previously opened form before opening the new form.
Element Description
form is the name of the 4GL screen form to be cleared from memory.
CLOSE FORM form
4-32 INFORMIX- 4GL Reference Manual
CLOSE FORM
References
CLOSE WINDOW, DISPLAY FORM, OPEN FORM, OPEN WINDOW
INFORMIX- 4GL Statements 4-33
CLOSE WINDOW
CLOSE WINDOW
The CLOSE WINDOW statement closes a specied 4GL window.
Usage
The CLOSE WINDOW statement causes 4GL to take the following actions:
B Clears the specied 4GL window from the 4GL screen and restores
any underlying display
B Frees all resources used by the 4GL window and deletes it from the
4GL window stack
B If the OPEN WINDOW statement included the WITH FORM clause,
closes both the form and the window
4GL maintains an ordered list of open 4GL windows, called the window stack.
When you open a new4GL window, it is added to the stack and becomes the
current window, occupying the top of the stack. Closing the current window
makes the next 4GL window on the stack the new current window. If you
close any other window, 4GL deletes it from the stack, leaving the current
window unchanged. Closing a window has no effect on variables that were
set while the windowwas open. The following programfragment opens and
closes a 4GL window called stock_w:
OPEN WINDOW stock_w AT 7, 3 WITH 6 ROWS, 70 COLUMNS
CLOSE WINDOW stock_w
You cannot specify CLOSE WINDOWSCREEN. If window is currently being
used for input, CLOSE WINDOWgenerates a runtime error. For example, you
cannot close the current 4GL windowwhile a CONSTRUCT, DISPLAY ARRAY,
INPUT, INPUT ARRAY, or MENU statement is executing.
Element Description
window is the identier of the 4GL window to be closed.
CLOSE WINDOW window
4-34 INFORMIX- 4GL Reference Manual
CLOSE WINDOW
References
CLEAR, CLOSE FORM, CURRENT WINDOW, OPEN WINDOW, OPTIONS
INFORMIX- 4GL Statements 4-35
CONSTRUCT
CONSTRUCT
The CONSTRUCT statement stores in a character variable a 4GL Boolean
expression that corresponds to query by example criteria that a user species.
You can use this variable in the WHERE clause of a SELECT statement.
Usage
The CONSTRUCT statement is designed to enable users to performa query by
example. Query by example enables a user to query a database by specifying
values (or ranges of values) for screen elds that correspond to database
columns. 4GL converts these values into a Boolean expression that species
search criteria that can appear in the WHERE clause of a prepared SELECT
statement.
Element Description
number is a literal integer (as described in Literal Integers on page 3-65),
specifying a help message number.
variable is the identier of a CHAR or VARCHAR variable that stores a 4GL
Boolean expression summarizing the user-entered search criteria.
HELP number
ATTRIBUTE Clause
p. 3-97
CONSTRUCT
Input Control Block
p. 4-45
CONSTRUCT
Variable
Clause
CONSTRUCT
variable ON FROM
Field List
p. 4-38
BY NAME variable ON
Column List
p. 4-38
CONSTRUCT
Variable Clause
Column List
p. 4-38
END CONSTRUCT
4-36 INFORMIX- 4GL Reference Manual
CONSTRUCT
The CONSTRUCT statement can also control the environment in which the
user enters search criteria, and can restrict the values that the user enters. To
use the CONSTRUCT statement, you must do the following:
B Dene elds linked to database columns in a form specication le.
B Declare a character variable with the DEFINE statement.
B Open and display the screen form with either of the following:
O OPEN FORM and DISPLAY FORM statements
O OPEN WINDOW statement with a WITH FORM clause
B Use CONSTRUCT to store in the character variable a Boolean
expression that is based on criteria that the user enters in the elds.
The CONSTRUCT statement activates the current form. This is the formmost
recently displayed or, if you are using more than one 4GL window, the form
currently displayed in the current window. You can specify the current
windowby using the CURRENT WINDOWstatement. When the CONSTRUCT
statement completes execution, the form is deactivated.
When it encounters the CONSTRUCT statement, 4GL takes the following
actions at runtime:
1. Clears all the screen elds of the CONSTRUCT eld list
2. Executes the statements in the BEFORE CONSTRUCT control block,
if the CONSTRUCT statement includes that control block
3. Moves the screen cursor to the rst screen eld in that list
4. Waits for the user to enter some value as search criteria in the eld
For elds where the user enters no value, any value in the corre-
sponding database column satises the search criteria.
After the user presses the Accept key (typically ESCAPE), CONSTRUCT uses
AND operators to combine eld values as search criteria in a Boolean
expression, and stores this in the character variable. If no criteria were
entered, the TRUE expression " 1=1" is assigned to the character variable.
INFORMIX- 4GL Statements 4-37
CONSTRUCT
By performing the following steps, you can use this variable in a WHERE
clause to search the database for matching rows:
1. Concatenate the variable that contains the Boolean expression with
other strings to create a string representation of an SQL statement to
be executed.
The Boolean expression generated by the CONSTRUCT statement is
typically used to create SELECT statements.
2. Use the PREPARE statement to create an executable SQL statement
from the character string that was generated in the previous step.
3. Execute the prepared statement in one of the following ways:
B Use an SQL cursor with DECLARE and FOREACH statements (or
else OPENand FETCHstatements) to execute a prepared SELECT
statement that includes no INTO clause.
B Use the EXECUTE statement to execute an SQL statement other
than SELECT, or to execute a SELECTINTO statement.
When the CONSTRUCT statement completes execution, the form is cleared.
Environment variables that format data values, such as DBDATE, DBTIME,
DBFORMAT, DBFLTMASK, and DBMONEY, have no effect on the contents of
the Boolean expression.
The following topics are described in this section:
B The CONSTRUCT Variable Clause on page 4-38
B The ATTRIBUTE Clause on page 4-42
B The HELP Clause on page 4-44
B The CONSTRUCT Input Control Blocks on page 4-45
B The NEXT FIELD Clause on page 4-53
B The END CONSTRUCT Keywords on page 4-56
B Using Built-In Functions and Operators on page 4-56
B Search Criteria for Query by Example on page 4-57
B Positioning the Screen Cursor on page 4-62
B Using WORDWRAP in CONSTRUCT on page 4-63
B Editing During a CONSTRUCT Statement on page 4-64
B Completing a Query on page 4-64
4-38 INFORMIX- 4GL Reference Manual
CONSTRUCT
The CONSTRUCT Variable Clause
The CONSTRUCT variable clause species a character variable to store search
criteria that the user can enter in screen elds for database columns.
Element Description
column is the unqualied identier of a database column in table.
database is the identier of the database in which the table resides.
eld is the identier of a screen eld.
line is an integer expression, identifying a record in screen array.
owner is the user name of the owner of the table containing the column.
screen array is the 4GL identier of a screen array in the current form.
screen record is the 4GL identier of a screen record or else a table reference
(as the name of a default screen record).
server is the name of the host system where database resides.
table is the name, alias, or synonym of a database table or view.
variable is the identier of a CHAR or VARCHAR variable.
CONSTRUCT Variable Clause
database
,
table .
column
*
owner .
:
: @ server
IDS
,
.
*
eld
THRU
Notation
p. 3-93
screen
record
screen
array
.
variable ON FROM
Field List
variable ON
Column List
table
[ 1 ]
[ line ]
Column List
Field List
Column List
BY NAME
INFORMIX- 4GL Statements 4-39
CONSTRUCT
The CONSTRUCT variable clause temporarily binds the specied screen elds
to database columns and species the database columns for which the user
can enter search criteria. You can map the elds implicitly (with the BYNAME
keywords) or explicitly (with the FROM keyword and eld list). With either
method, each eld and corresponding column must be of the same or
compatible data types. The order of elds in the FROMclause determines the
default sequence in which the screen cursor moves from eld to eld in the
form. Within a screen array, you can specify only one screen record.
Here the eld list is a restricted subset of the eld clause that some 4GL screen
interaction statements support (as described in Field Clause on page 3-87).
In a eld list within the CONSTRUCT variable clause, a table reference cannot
include table qualiers. You must declare an alias in the form specication
le, as described in Table Aliases on page 6-24, for any table reference that
requires a qualifying prex (such as database, server, or owner).
4GL constructs a character variable by associating each column name in the
ON clause with search criteria that the user enters into the corresponding
eld (as specied in the FROMclause, or implied by the BY NAME keywords).
You can use the information stored in character variable in the WHERE clause
of a prepared SELECT statement to retrieve rows fromthe database. To avoid
overow, declare the length of variable as several times the total length of all
the elds, because the Boolean expression includes additional operators.
The BY NAME Keywords
You can use the BY NAME clause when the elds on the screen formhave the
same names as the corresponding columns in the ON clause. The BY NAME
clause maps the form elds to columns implicitly. The user can query only
the screen elds implied in the BY NAME clause. The following CONSTRUCT
statement, for example, assigns search criteria to the variable query_1:
CONSTRUCT BY NAME query_1 ON company, address1, address2,
city, state, zipcode
The user can enter search criteria in the elds named company, address1,
address2, city, state, and zipcode. Because these elds have the same names
as the columns specied after the ON keyword, the statement uses the BY
NAME clause. If the eld names do not match the column names, you must
use the FROM clause instead of the BY NAME clause.
4-40 INFORMIX- 4GL Reference Manual
CONSTRUCT
This functionally equivalent CONSTRUCT statement uses the FROM clause:
CONSTRUCT query_1
ON company, address1, address2, city, state, zipcode
FROM company, address1, address2, city, state, zipcode
If the column names in a CONSTRUCT BY NAME statement are associated
with eld names in a screen array, the construct takes place in the rst rowof
the screen array. If you want the CONSTRUCT to take place in a different row
of the screen array, you must use the FROMclause, not the BY NAME clause.
You cannot preface column names with a qualier that includes an owner
name, a database server name, or a pathname when you use the BY NAME
clause. Use the FROMclause to specify table aliases in the eld list when the
qualier of any column name requires an owner name, a database server
name, or a pathname.
The ON Keyword and Columns List
The ON clause species a list of database columns for which the user will
enter search criteria. Columns do not have to be from the same table. The
table can be in the specied database, in DBPATH, or in the current database
as specied by a DATABASE statement in this programblock. (For more infor-
mation, see The Current Database at Runtime on page 4-76.)
If the CONSTRUCT statement includes the BY NAME keywords, be sure that
the elds on the screen formhave the same names as the columns listed after
the ON keyword. If the CONSTRUCT statement includes a FROM clause, the
expanded list of columns in the ON clause must correspond in order and in
number to the expanded list of elds in the FROM clause.
You can use the notation table.* (as described in THRU or THROUGH
Keywords and .* Notation on page 3-93), meaning every column in table,
for all or part of the column list. The order of columns within table depends
on their order in the syscolumns system catalog table when you compile
your program. If the ALTER TABLE statement has changed the order, the
names, the data types, or the number of the columns in table since you
compiled your program, you might need to modify your program and its
screen forms that reference that table.
INFORMIX- 4GL Statements 4-41
CONSTRUCT
The following example uses the customer.* notation as a macro for listing all
columns in the customer table and cust.* as a macro for all the elds in the
customer screen record:
CONSTRUCT query_1 ON customer.* FROM cust.*
The FROM Keyword and Field List
The FROMclause species a list of screen elds or screen records in the form.
You cannot use the FROMclause if you include the BY NAME clause, but you
must use the FROM clause if any of the following conditions is true:
B The names of elds on the screen formare different fromthe names
of the corresponding database columns in the ON clause.
B You want to reference elds in a screen array beyond the rst record.
B Youspecify additional qualiers for table.column in the ONclause (for
example, for external or non-unique table names, or to reference the
owner of a table if the database is ANSI-compliant).
B You want to specify an order for the screen elds other than the
default order. (The order of the elds in the screen record determines
the default order of the screen elds.)
The user can position the cursor only in elds specied in the FROM clause.
The list of elds in the FROMclause must correspond in order and in number
to the list of database columns in the ON clause, as in this example:
CONSTRUCT query_1 ON stock_num, manu_code, description
FROM stock_no, m_code, descr
If you use the record.* notation in a eld list, be sure that the implied order of
elds corresponds to the order of columns in the ON clause. (The order of
elds in a screen record depends on its denition in the form specication.)
In the following CONSTRUCT statement, the eld list includes the stock_num
andmanu_code elds, as well as the screenrecords_stock.* that corresponds
to the remaining columns in the stock table:
CONSTRUCT query_1 ON stock.*
FROM stock_num, manu_code, s_stock.*
4-42 INFORMIX- 4GL Reference Manual
CONSTRUCT
The FROMclause is required when the eld list includes an alias representing
a table, view, or synonym name that includes any qualier. For example, in
the following CONSTRUCT statement, cust is a table alias declaredin the form
specication le for the actg.customer table, where actg is an owner prex.
This table alias must be prexed to each eld name in the FROM clause,
because the column qualiers in the ON clause include an owner name:
CONSTRUCT query_1 ON
actg.customer.fname, actg.customer.lname,
actg.customer.company
FROM cust.fname, cust.lname, cust.company
To use screen-array eld names in the FROM clause, you must use the
notation screen-record [line].eld-name to specify the row in which the
construct takes place. Here line must be greater than zero, and the
CONSTRUCT takes place on the lineth record of the screen array. For example,
the following CONSTRUCT statement allows youto enter searchcriteria in the
third line of the screen array s_items:
CONSTRUCT query_1 ON items.* FROM s_items[3].*
If you reference a screen array in the eld list with no [line] specication, the
default is the rst screen record of the array.
The ATTRIBUTE Clause
For general information about the color and intensity attributes that can be
specied for the attribute clause, see ATTRIBUTE Clause on page 3-97.
Attributes in CONSTRUCT Statements
The ATTRIBUTE clause in a CONSTRUCT statement applies display attributes
to all the elds specied implicitly in the BY NAME clause or explicitly in the
FROM clause. If you use the ATTRIBUTE clause, the following attributes do
not apply to the elds:
B Default attributes listed in syscolatt table
(See the description of The upscol Utility on page B-5.)
B Default attributes in the form specication
B The NOENTRY and AUTONEXT attribute in the form specication
INFORMIX- 4GL Statements 4-43
CONSTRUCT
Whether or not the CONSTRUCT statement includes the ATTRIBUTE clause,
when the user enters criteria into a eldthat has the AUTONEXT attribute and
keys past the eld delimiter, the cursor does not enter the next eld.
The CONSTRUCT statement ignores the AUTONEXT attribute so that users can
query for large ranges, alternatives, and so forth.
The CONSTRUCT attributes temporarily override any display attributes set
by the INPUT ATTRIBUTE clause of an OPTIONS or OPENWINDOWstatement.
Attributes in the ATTRIBUTE clause of CONSTRUCT apply to all the elds in
the eld list, but only during the current activation of the form. When the
user deactivates the form, the form reverts to its previous attributes.
The following CONSTRUCT statement includes an ATTRIBUTE clause that
species CYANand REVERSE for values entered in screen elds that have the
same names as the columns in the customer table:
CONSTRUCT BY NAME query_1 ON customer.*
ATTRIBUTE (CYAN, REVERSE)
These keywords can produce the effects indicated only when the termcap or
terminfo les and the physical terminals support the specied attribute. For
more information on using these les, see Appendix F, Modifying termcap
and terminfo. On UNIX systems that use terminfo les rather than termcap,
4GL does not support attributes that specify colors, and the only valid
keywords are REVERSE and UNDERLINE.
Some terminal entries in termcap or terminfo can include sg#1 or xmc#1
capabilities. If you are using one of these terminals and if the attributes
specied for the CONSTRUCT statement are different from the attributes of
the current formor window, 4GL replaces the right andleft ( [ ] ) brackets that
indicate the input elds with blank characters. 4GL uses the blank character
as a transition character between the different attributes.
4-44 INFORMIX- 4GL Reference Manual
CONSTRUCT
The HELP Clause
The optional HELP clause species the number of a help message associated
with this CONSTRUCT statement. This might describe, for example, the role
of the user in query by example. The message appears in the Help window
when the user presses the Help key fromany eld in the eld list. By default,
the Help key is CONTROL-W, but the OPTIONS statement can assign a different
physical key as the Help key.
You create help messages in an ASCII le. The number identies the message
in the help le. The help le is a compiled message le whose name you
specify in the HELP FILE clause of the OPTIONS statement. The mkmessage
utility can create a compiled version of the help le. For details of how to
create a runtime version of the help le, see The mkmessage Utility on
page B-2. An error occurs if 4GL cannot open the help le, or if number is not
in the help le, or is greater than 32,767.
To provide eld-level help, use an ON KEY clause (as described in The ON
KEY Blocks on page 4-48) with the INFIELD( ) operator and SHOWHELP( )
function; both are described in Chapter 5. If you provide messages to assist
the user through an ON KEY clause, rather than by the HELP clause, the
message must be displayed in a 4GL window within the 4GL screen, rather
than in the separate Help window.
INFORMIX- 4GL Statements 4-45
CONSTRUCT
The CONSTRUCT Input Control Blocks
Each CONSTRUCT input control block includes a statement block of at least
one statement, and an activation clause that species when to execute the
block. The activation clause and statement block correspond respectively to
the left-hand and right-hand syntax elements in the following diagram.
You can use CONSTRUCT input control blocks to specify the following:
B Statements to execute before and after the query by example
B Statements to execute before and after a given eld
B Statements to execute if a user presses some key sequence
B The next eld to which to move the screen cursor
B When to exit from the CONSTRUCT statement
CONSTRUCT
Input Control Block
BEFORE CONSTRUCT 1
AFTER CONSTRUCT 1
,
eld AFTER FIELD
ON KEY
,
key
) (
statement
NEXT FIELD PREVIOUS
NEXT
CONTINUE CONSTRUCT
EXIT CONSTRUCT
Field Clause
p. 3-87
BEFORE FIELD
Element Description
eld is the name of a eld that was either explicitly or implicitly
referenced in the CONSTRUCT variable clause (page 4-38).
key is a keyword listed in The ON KEY Blocks on page 4-48.
statement is an SQL statement or other 4GL statement.
4-46 INFORMIX- 4GL Reference Manual
CONSTRUCT
4GL executes the statements in the block according to the following events:
B The elds into which and from which the user moves the cursor
B The keys that the user presses
Statements can include CONTINUE CONSTRUCT and EXIT CONSTRUCT, the
NEXT FIELD clause, and most 4GL and SQL statements. See Nested and
Recursive Statements on page 2-31 for details of including CONSTRUCT,
PROMPT, INPUT, and INPUT ARRAY statements within an input control block.
4GL temporarily deactivates the formwhile executing statements in an input
control block. After executing the statements, 4GL reactivates the form,
allowing the user to continue modifying values in elds.
The Precedence of Input Control Blocks
The CONSTRUCT statement can list input control blocks in any order. You
shoulddevelop some consistent ordering, however, so that your code is more
readable than if the blocks were randomly ordered. When you use one or
more input control blocks, you must include the ENDCONSTRUCT statement
to terminate the CONSTRUCT statement. If you include several input control
blocks, 4GL processes themin the following sequence, regardless of the order
in which they appear in the CONSTRUCT statement:
1. BEFORE CONSTRUCT (executed before the user begins data entry)
2. BEFORE FIELD(executed before the user enters values in a specied
eld)
3. ON KEY (executed after the user presses a specied key)
4. AFTER FIELD (executed after the user enters values in a specied
eld)
5. AFTER CONSTRUCT (executed after the user has nished data entry)
If you include no input control blocks, the program waits while the user
enters values in the elds. When the user accepts the values in the form, the
CONSTRUCT statement terminates, the form is cleared, and control passes
to the next statement.
INFORMIX- 4GL Statements 4-47
CONSTRUCT
The BEFORE CONSTRUCT Block
The BEFORE CONSTRUCT control block species a series of actions to perform
before the user begins entering criteria into the screen elds. 4GL sets the
values of all the screen elds to blank spaces when the CONSTRUCT
statement begins execution. You can use the BEFORE CONSTRUCT block to
supply different initial default values for the elds.
CONSTRUCT executes the statements in the BEFORE CONSTRUCT block once
before it allows the user to perform the query by example. You can use
DISPLAY statements in the BEFORE CONSTRUCT block to populate the elds;
DISPLAY initializes the eld buffers to the displayed values. (To specify the
rst eld where criteria can be entered, you can use the NEXT FIELD clause.)
For example, the following DISPLAY statement assigns the values in the rec
program record to the eld buffers associated with the srec screen record:
BEFORE CONSTRUCT
DISPLAY rec.* TO srec.*
NEXT FIELD lname
The following CONSTRUCT statement displays the value HRO in the
manu_code eld. If the user does not change the HRO value before pressing
the Accept key, the query by example selects rows of the database that have
the value HRO in the manu_code column:
CONSTRUCT query_1 ON stock.* FROM s_stock.*
BEFORE CONSTRUCT
LET p_stock.manu_code = "HRO"
DISPLAY p_stock.manu_code TO stock.manu_code
END CONSTRUCT
No more than one BEFORE CONSTRUCT block can appear in a CONSTRUCT
statement. The FIELD_TOUCHED( ) operator is not valid in this control block.
The BEFORE FIELD Blocks
This control block species a series of actions to execute before the cursor is
placed in a specied screen eld. 4GL executes the BEFORE FIELD block of
statements whenever the screen cursor enters the eld, and before the user
types search criteria. Aeld can have no more than one BEFORE FIELD block.
You can use a NEXT FIELD clause within a BEFORE FIELD block to restrict
access to a eld. You can also use a DISPLAY statement within a BEFORE
FIELD block to display a default value in a eld.
4-48 INFORMIX- 4GL Reference Manual
CONSTRUCT
The following example uses the BEFORE FIELD clause to display a message
when the cursor enters the state eld:
BEFORE FIELD state
MESSAGE "Press F2 or CTRL-B to display a list of states"
The following programfragment denes two BEFORE FIELD blocks. The rst
block uses the NEXT FIELD clause to limit access to the salary eld to certain
users. The second block displays the current date in the q_date eld:
CONSTRUCT BY NAME query_1 ON employee.*
BEFORE FIELD salary
IF (username <> "manager") AND (username <> "admin")
THEN NEXT FIELD NEXT
END IF
BEFORE FIELD q_date
LET query_date = TODAY
DISPLAY query_date TO q_date
END CONSTRUCT
The ON KEY Blocks
The ON KEY control blocks specify actions to take when the user presses
certain function or control keys. The statements in the appropriate ON KEY
block are executed if the user presses the activation key corresponding to one
of your key specications.
The next example uses the ON KEY clause to call a help message. Here the
BEFORE CONSTRUCT clause informs you how to access help:
BEFORE CONSTRUCT
DISPLAY "Press F1 or CTRL-W for help"
ON KEY (f1, control-w)
CALL customer_help()
The following table lists the keywords that you can specify for key.
Like other keywords of 4GL, you can specify these in uppercase or lowercase
letters.
ACCEPT HELP NEXT or NEXTPAGE
DELETE INSERT PREVIOUS or PREVPAGE
DOWN INTERRUPT RETURN
ESC or ESCAPE LEFT TAB
F1 through F64 RIGHT UP
CONTROL-char (except A, D, H, I, J, K, L, M, R, or X)
INFORMIX- 4GL Statements 4-49
CONSTRUCT
Some keys need special consideration if you assign themin an ONKEY block.
You might not be able to use other keys that have special meaning to your
version of the operating system. For example, CONTROL-C, CONTROL-Q, and
CONTROL-S respectively send the Interrupt, XON, and XOFF signals on many
systems.
If an ON KEY block is activated during data entry, 4GL takes these actions:
1. Suspends the input of the current eld
2. Preserves the input buffer that holds the characters the user typed
3. Executes the statements in the corresponding ON KEY clause
Key Special Considerations
ESC or ESCAPE You must use the OPTIONS statement to specify another key as
the Accept key, because ESCAPE is the default Accept key.
F3 You must use the OPTIONS statement to specify another key as
the Next key, because F3 is the default Next key.
F4 You must use the OPTIONS statement to specify another key as
the Previous key, because F4 is the default Previous key.
INTERRUPT You must execute a DEFER INTERRUPT statement. When the
user presses the Interrupt key under these conditions, 4GL
executes the ONKEYblock andsets int_ag to non-zero but does
not terminate the CONSTRUCT statement. Similarly, 4GL
executes the statements in the ON KEY block and sets quit_ag
to non-zero if the DEFER QUIT statement has been executed
when the user presses the Quit key.
CTRL-char
A, D, H,
L, R, X
4GL reserves these control keys for eld editing; see Positioning
the Screen Cursor on page 4-62.
I, J, M The standard meaning of these keys (TAB, LINEFEED, and
RETURN, respectively) is not available to the user. Instead, the key
is trapped by 4GL and activates the commands in the ON KEY
block. For example, if CONTROL-Mappears in an ON KEY block,
the user cannot press RETURN to advance the cursor to the next
eld. If you specify one of these keys in an ON KEY block, be
careful to restrict the scope of the statement.
4-50 INFORMIX- 4GL Reference Manual
CONSTRUCT
4. Restores the input buffer for the current screen eld
5. Resumes input in the same eld, with the cursor at the end of the
buffered list of characters
You can change this default behavior by including statements to performthe
following tasks in the ON KEY block:
B Resume input in another eld by using the NEXT FIELD keywords
B Change the input buffer value for the current eld by assigning a
new value to the corresponding variable and displaying the value
Version 4.12 of 4GL introduced a change in the output of CONSTRUCT state-
ments interrupted by the user pressing the Interrupt key (usually CTRL-C or
DEL) or the Quit key (usually CTRL-\). This applies only to programs that have
executedDEFERINTERRUPT andDEFERQUIT; otherwise, an Interrupt or Quit
signal terminates the 4GL application immediately.
In 4.10 and earlier releases, an Interrupt or Quit keystroke in a CONSTRUCT
statement produced an output query string that contained the contents of the
eld buffer at the time the Interrupt keystroke was pressed. Therefore, if the
program did not carefully check the value of int_ag before proceeding, it
could miss the fact that the CONSTRUCT had been interrupted and proceed
with a query that was based on defective search criteria.
In Version 4.12 and later, a CONSTRUCT statement interrupted by an
Interrupt or Quit keystroke produces a NULL query string. This reduces the
risk of an Interrupt condition being undetected. The CONSTRUCT statement
can only produce a NULL query string if it was interrupted; thus, you can
detect an Interrupt or Quit without checking both int_ag and quit_ag. (A
successful CONSTRUCT statement for which no criteria were entered before
the Accept key was pressed produces the string " 1=1", not a NULL string.)
INFORMIX- 4GL Statements 4-51
CONSTRUCT
The AFTER FIELD Blocks
4GL executes the AFTER FIELD block associated with a eld when the screen
cursor leaves the eld. The user can move the cursor froma eld by pressing
any of the following keys:
B Any arrow key
B RETURN key
B Accept key
B TAB key
When the NEXT FIELDkeywords appear in an AFTER FIELDblock, 4GL places
the cursor in the specied eld and ignores the Accept keystroke. If an AFTER
FIELD block exists for each eld, and if a NEXT FIELD clause appears in every
AFTER FIELD block, the user is unable to leave the form.
The following program fragment checks for the Accept key and terminates
execution of CONSTRUCT if the Accept key was pressed:
AFTER FIELD status
IF NOT GET_LASTKEY( ) = ACCEPT_KEY THEN
LET p_stat = GET_FLDBUF(status)
IF p_stat MATCHES "married" THEN
NEXT FIELD spouse_name
END IF
END IF
END CONSTRUCT
The following AFTER FIELDcontrol block displays a message after the cursor
leaves the state eld, prompting the user to enter search criteria:
AFTER FIELD state
MESSAGE "Press ESC to begin search"
As noted in Completing a Query on page 4-64, the user can terminate the
CONSTRUCT statement by using Accept, Interrupt, or Quit, or by pressing the
TAB or RETURN key after the last form eld. You can use the AFTER FIELD
clause with the NEXT FIELDkeywords on the last eldto override this default
termination. (Alternatively, you can specify INPUT WRAP in an OPTIONS
statement to achieve the same effect.)
A eld can have no more than one AFTER FIELD control block.
4-52 INFORMIX- 4GL Reference Manual
CONSTRUCT
The AFTER CONSTRUCT Block
This control block species statements to execute after the user presses
Accept and before 4GL constructs the string containing the Boolean
expression. You can use the AFTER CONSTRUCT block to validate, save, or
alter the values of the screen eld buffers. Using Built-In Functions and
Operators on page 4-56 describes some built-in functions and operators of
4GL that commonly appear in the AFTER CONSTRUCT block.
You can specify CONTINUE CONSTRUCT or NEXT FIELD in this block to
return the cursor to the form. If you include these keywords in the AFTER
CONSTRUCT block, be sure that they appear within a conditional statement.
Otherwise, the user cannot exit from the CONSTRUCT statement and leave
the form.
In the following program fragment, a CONTINUE CONSTRUCT statement
appears in an IF statement. If the user does not specify any selection criteria,
4GL returns the screen cursor to the form.
AFTER CONSTRUCT
IF NOT FIELD_TOUCHED(orders.*) THEN
MESSAGE "You must indicate at least one ",
"selection criteria."
CONTINUE CONSTRUCT
END IF
For more information, see Searching for All Rows on page 4-61.
4GL executes the statements in the AFTER CONSTRUCT block when the user
presses any of the following keys:
B The Accept key
B The Interrupt key (if DEFER INTERRUPT has executed)
B The Quit key (if the DEFER QUIT statement has executed)
The AFTER CONSTRUCT block is not executed in the following situations:
B The user presses the Interrupt or Quit key andthe DEFERINTERRUPT
or DEFER QUIT statement, respectively, has not been executed. In
either case, the program terminates immediately, and no query is
performed.
B The EXIT CONSTRUCT statement terminates the CONSTRUCT
statement.
INFORMIX- 4GL Statements 4-53
CONSTRUCT
The CONSTRUCT statement can include only one AFTER CONSTRUCT block.
The NEXT FIELD Clause
While the CONSTRUCT statement is executing, 4GL moves the screen cursor
from eld to eld in the order specied in the FROM clause, or in the order
implied by the ON clause of the CONSTRUCT BY NAME statement. You can
use the NEXT FIELD keywords, however, to override the default sequence of
cursor movement.
You can specify any of the following elds in the NEXT FIELD clause:
B The next eld, as denedby the explicit (FROMclause) or implicit (BY
NAME) order of elds in the eld list of the CONSTRUCT variable
clause. In this case, specify the NEXT keyword.
B The previous eld, as denedby the same order of elds. In this case,
specify the PREVIOUS keyword.
B Any other eld in the current form. In this case, specify the name of
the eld (fromthe ATTRIBUTES section of the formspecication le).
The NEXT FIELD keywords can appear in a BEFORE CONSTRUCT block (for
example, to position the cursor at a different starting eld) and in a BEFORE
FIELD block (for example, to restrict access to a eld), but they are more
commonly used in AFTER FIELD, ON KEY, or AFTER CONSTRUCT blocks.
Use NEXT FIELD only if you want the cursor to deviate fromthe default eld
order. 4GL immediately positions the cursor in the form when it encounters
the NEXT FIELD clause, without executing any statements that immediately
follow the NEXT FIELD clause in the same statement block.
In the following program fragment, function qty_help( ) cannot be invoked
because its CALL statement is positioned after the NEXT FIELD clause:
ON KEY (CONTROL_B, F4)
IF INFIELD(stock_num) OR INFIELD(manufact) THEN
CALL stock_help( )
NEXT FIELD quantity
CALL qty_help( ) -- function is never called
END IF
4-54 INFORMIX- 4GL Reference Manual
CONSTRUCT
The following program fragment includes NEXT FIELD clauses in ON KEY
and AFTER FIELD blocks. The user triggers the ON KEY block by pressing
CONTROL-B or F4. If the cursor is in the stock_numeld or manufact eld, 4GL
calls the stock_help( ) function. When 4GL returns from the stock_help( )
function, the NEXT FIELD clause moves the cursor to the quantity eld.
The user executes the AFTER FIELD block by moving the cursor out of the
zipcode eld. The FIELD_TOUCHED( ) operator checks whether the user
entered a value into the eld. If this returns TRUE, GET_FLDBUF( ) retrieves
the value entered into the eld during a query, and assigns it to the
p_zipcode variable. If the rst character in the p_zipcode variable is not a 5,
4GL displays an error, clears the eld, and returns the cursor to the eld.
ON KEY (CONTROL_B, F4)
IF INFIELD stock_num) OR INFIELD(manufact) THEN
CALL stock_help( )
NEXT FIELD quantity
END IF
AFTER FIELD zipcode
IF FIELD_TOUCHED(zipcode) THEN
LET p_zipcode = GET_FLDBUF(zipcode)
IF p_zipcode[1,1] <> "5" THEN
ERROR "You can only search area 5."
CLEAR zipcode
NEXT FIELD zipcode
END IF
END IF
Do not use NEXT FIELD clauses to move the cursor across every eld in a
form. If you want the cursor to move in a specic order, list the elds in the
CONSTRUCT statement in the desired order. In most situations, NEXT FIELD
appears in a conditional statement. The NEXT FIELD clause must appear in a
conditional statement when it appears in an AFTER CONSTRUCT block;
otherwise, the user cannot exit from the query.
The CONTINUE CONSTRUCT Statement
You can use the CONTINUE CONSTRUCT statement to exit from a BEFORE
CONSTRUCT, AFTER CONSTRUCT, BEFORE FIELD, AFTER FIELD, or ON KEY
control block and return the cursor to the form, with the same CONSTRUCT
statement still in effect. The CONTINUE CONSTRUCT statement skips all
subsequent statements in the CONSTRUCT statement, and returns the cursor
to the screen form at the last eld occupied.
INFORMIX- 4GL Statements 4-55
CONSTRUCT
This statement is useful where program control is nested within multiple
conditional statements and you want to return control to the user. It is also
useful in an AFTER CONSTRUCT block, where you can examine eld buffers
and, depending on their contents, return the cursor to the form.
In this example, CONTINUE CONSTRUCT appears in an AFTER CONSTRUCT
clause. If the user enters N or n at the prompt, the cursor returns to the form:
CONSTRUCT BY NAME query1 ON customer.*
...
AFTER CONSTRUCT
IF NOT FIELD_TOUCHED(customer.*) THEN
PROMPT "Do you really want to see ",
"all customer rows? (y/n)" FOR CHAR answer
IF answer MATCHES "[Nn]" THEN
MESSAGE "Enter search criteria; ",
"press ESC to begin search."
CONTINUE CONSTRUCT
END IF
END IF
END CONSTRUCT
If no criteria are entered, the user is prompted to conrm that all customer
records are requested. If the user types N or n, CONTINUE CONSTRUCT
positions the cursor in the form, giving the user another chance to enter
selection criteria in the last eld occupied. If the user types any other key, the
IF statement terminates, and control passes to the END CONSTRUCT
statement. Compare this method of detecting and handling the absence of
search criteria to the examples in The AFTER CONSTRUCT Block on
page 4-52 and Searching for All Rows on page 4-61.
When a test in an AFTER CONSTRUCT clause identies a eld that requires
action by the user, specify NEXT FIELD, rather than CONTINUE CONSTRUCT,
to position the cursor in the eld.
The EXIT CONSTRUCT Statement
The EXIT CONSTRUCT statement causes 4GL to take the following actions:
B Skip all statements between EXIT CONSTRUCT and END
CONSTRUCT.
B Terminate the process of constructing the query by example.
B Create the Boolean expression and store it in the character variable.
4-56 INFORMIX- 4GL Reference Manual
CONSTRUCT
B Resume execution at the statement following the END CONSTRUCT
keywords.
If it encounters the EXIT CONSTRUCT statement, 4GL does not execute the
statemen