Four J’s Business

Development
Language User Guide
Version 3.10

Documentation Version 3.10.1f

March 2001
Part No. ACD00X
Copyright (c) 2000 Four J’s Development Tools, Ltd. - All rights reserved.

This product and related documentation is protected by copyright and distributed under licenses restricting its use,
copying, distribution and decompilation. No part of this product or related documentation may be reproduced in any form
by any means without prior written authorization of Four J’s Development Tools Ltd. and its licensors, if any.

Four J’s Buisiness Development Language and Dynamic Virtual Machine are trademarks or registered trademarks of
Four J’s Development Tools, Ltd.

Informix and Dynamic 4GL are registered trademarks of Informix Software, Inc. Motif, X Window System and UNIX
are registered trademarks of The Open Group in the US and other countries.

Java and all Java based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc.

SCO is a registered trademark of The Santa Cruz Operation, Inc.

Microsoft, Windows and Windows NT and/or other Microsoft products referenced herein are either trademarks or
registered trademarks of Microsoft Corporation.

Ataman is a registered trademark of Ataman Software, Inc.

All other product names mentioned herein are the trademarks of their respective owners.

ii Four J’s Business Development Language User Guide

Table of
Contents

Table of Contents

Introduction
In This Introduction . . . . . . . . . . . . . . . . . . . 3
About This Guide . . . . . . . . . . . . . . . . . . . . 3
Organization of This Guide . . . . . . . . . . . . . . . 3
Audience . . . . . . . . . . . . . . . . . . . . . 5
Software Dependencies . . . . . . . . . . . . . . . . . 5
Documentation Conventions . . . . . . . . . . . . . . . . 5
Typographical Conventions . . . . . . . . . . . . . . . 6
Icon Conventions . . . . . . . . . . . . . . . . . . 7
Additional Documentation . . . . . . . . . . . . . . . . . 7
Four J’s Welcomes Your Comments . . . . . . . . . . . . . . 8

Product Description
In This Chapter . . . . . . . . . . . . . . . . . . . . 1-3
Introducing Four J’s Business Development Language . . . . . . . . 1-3
Windows Interface . . . . . . . . . . . . . . . . . . 1-3
Web Interface . . . . . . . . . . . . . . . . . . . . 1-3
Text Interface . . . . . . . . . . . . . . . . . . . . 1-4
GLS Support . . . . . . . . . . . . . . . . . . . . 1-4
Three-Tier Client/Server Architecture . . . . . . . . . . . . 1-5
Client Example . . . . . . . . . . . . . . . . . . 1-6
Architecture . . . . . . . . . . . . . . . . . . . 1-6
Differences Between Four J’s Business Development Language and 4GL . . 1-7
Features Summary . . . . . . . . . . . . . . . . . . . . 1-12

Installation
In This Chapter . . . . . . . . . . . . . . . . . . . . . 2-3
Before Installing Four J’s Business Development Language. . . . . . . 2-3
Release Notes . . . . . . . . . . . . . . . . . . . . . 2-3
Hardware requirements . . . . . . . . . . . . . . . . . . 2-3
Disk Space Requirement . . . . . . . . . . . . . . . . 2-3
Software requirements . . . . . . . . . . . . . . . . . . 2-4
Licensing the Product . . . . . . . . . . . . . . . . . . . 2-4
Supported Operating Systems . . . . . . . . . . . . . . . . 2-5
Upgrading Four J's BDL . . . . . . . . . . . . . . . . . . 2-6
Product Information Viewer . . . . . . . . . . . . . . . . . 2-6
Product Directory Structure . . . . . . . . . . . . . . . . . 2-7
Post Installation Tasks . . . . . . . . . . . . . . . . . . 2-8
UNIX installation . . . . . . . . . . . . . . . . . . . . 2-8
Installation Program Requirements . . . . . . . . . . . . . 2-8
TCP/IP Requirements . . . . . . . . . . . . . . . . . 2-8
C/C++ Compiler Requirements . . . . . . . . . . . . . . 2-9
Informix Prerequisites . . . . . . . . . . . . . . . . . 2-9
Prerequisites for GLS . . . . . . . . . . . . . . . . 2-9
Start the Installation on Unix . . . . . . . . . . . . . . . 2-9
Windows installation . . . . . . . . . . . . . . . . . . . 2-10
TCP/IP Requirements . . . . . . . . . . . . . . . . . 2-10
C/C++ Compiler Requirements . . . . . . . . . . . . . . 2-11
Using Windows Front End on the same machine . . . . . . . . . 2-11
Informix Prerequisites . . . . . . . . . . . . . . . . . 2-11
Start the Installation on Windows. . . . . . . . . . . . . . 2-11

First Steps

iv Four J’s Business Development Language User Guide

In This Chapter . . . . . . . . . . . . . . . . . . . . . 3-3
Setting the Environment Variables . . . . . . . . . . . . . . . 3-3
Compiling a Simple Program . . . . . . . . . . . . . . . . . 3-4
Writing the Source Code . . . . . . . . . . . . . . . . . 3-5
Compiling the Source Code . . . . . . . . . . . . . . . . 3-6
Compiling to P Code . . . . . . . . . . . . . . . . . 3-6
Compiling to C Code. . . . . . . . . . . . . . . . . 3-6
Compiling the Form-Specification File . . . . . . . . . . . . 3-7
Viewing the Four J’s Business Development Language Application . . . 3-8

Using the Compiler

In This Chapter . . . . . . . . . . . . . . . . . . . . . 4-4
Setting Environment Variables for the Compiler . . . . . . . . . . . 4-4
Compiling Form-Specification Files and Help Message Files . . . . . . . 4-5
Compiling Form-Specification Files . . . . . . . . . . . . . 4-5
Compiling Help Message Files . . . . . . . . . . . . . . . 4-6
Generating a Database Schema File . . . . . . . . . . . . . . . 4-6
Compiling to P Code . . . . . . . . . . . . . . . . . . . 4-7
Overview of a P-Code Example. . . . . . . . . . . . . . . 4-7
Compiling Source Files to Linkable Modules . . . . . . . . . 4-8
Linking Modules Together to Create P Code . . . . . . . . . 4-8
Using C Functions in 4GL Applications . . . . . . . . . . . . 4-9
Compatibility Problems with C . . . . . . . . . . . . . 4-9
Support for Variable Varameters in C Functions. . . . . . . . . 4-9
Linking C Functions with the P-Code Runner . . . . . . . . . 4-11
The C extension file . . . . . . . . . . . . . . . . . 4-14
Example . . . . . . . . . . . . . . . . . . . . . 4-14
Compiling to C Code . . . . . . . . . . . . . . . . . . . 4-19
Overview of a C-Code Example . . . . . . . . . . . . . . 4-19
Compiling Source Files to Linkable Modules . . . . . . . . . 4-20
Linking Modules to Create C-Code Libraries . . . . . . . . . 4-20
Using C Functions in 4GL Applications . . . . . . . . . . . . 4-21
Linking C Functions for Use in C-Code Compilations . . . . . . 4-21
Compilation Tools . . . . . . . . . . . . . . . . . . . . 4-26
Main Compilation Tools . . . . . . . . . . . . . . . . . 4-26
fgl2p . . . . . . . . . . . . . . . . . . . . . . 4-27
fgl2c . . . . . . . . . . . . . . . . . . . . . . 4-29
fglcomp . . . . . . . . . . . . . . . . . . . . . 4-32
fgllink . . . . . . . . . . . . . . . . . . . . . 4-33

Table of contents v
fglform . . . . . . . . . . . . . . . . . . . . 4-35
fglschema . . . . . . . . . . . . . . . . . . . . 4-36
fgldbsch . . . . . . . . . . . . . . . . . . . . 4-36
fglmkmsg . . . . . . . . . . . . . . . . . . . . 4-37
ar42o . . . . . . . . . . . . . . . . . . . . . 4-38
findlib.sh . . . . . . . . . . . . . . . . . . . . 4-39
Configuration Tools . . . . . . . . . . . . . . . . . . 4-41
fglmode . . . . . . . . . . . . . . . . . . . . 4-42
licencef4gl . . . . . . . . . . . . . . . . . . . 4-44
fglfontsel, fglfontsel.42e . . . . . . . . . . . . . . . 4-45
Miscellaneous Programs and Scripts . . . . . . . . . . . . . 4-46
rtsinstall, fglinstall . . . . . . . . . . . . . . . . . 4-47
fglpager, pager.42e . . . . . . . . . . . . . . . . . 4-47
fglX11d . . . . . . . . . . . . . . . . . . . . 4-48
fglWrt . . . . . . . . . . . . . . . . . . . . . 4-48

Language Extensions
In This Chapter . . . . . . . . . . . . . . . . . . . . . 5-5
Integer Expressions as Character Subscripts . . . . . . . . . . . . 5-6
Integer Expressions as Array Indexes . . . . . . . . . . . . . . 5-6
Channel Extensions . . . . . . . . . . . . . . . . . . . 5-6
Initializing Channel Extensions . . . . . . . . . . . . . . 5-7
Opening a File. . . . . . . . . . . . . . . . . . . . 5-7
Opening a Pipe . . . . . . . . . . . . . . . . . . . 5-8
Setting the Default Separator . . . . . . . . . . . . . . . 5-9
Reading Data from an Opened Channel . . . . . . . . . . . . 5-9
Writing Data to a Pipe or Stream . . . . . . . . . . . . . . 5-10
Closing the Channel . . . . . . . . . . . . . . . . 5-11
Channel Error Codes. . . . . . . . . . . . . . . . . . 5-11
Sharing Information Using DDE . . . . . . . . . . . . . . . 5-11
Supported Windows Applications . . . . . . . . . . . . . 5-12
Using DDE Extensions . . . . . . . . . . . . . . . . . 5-12
Transmitting Values to a Windows Program . . . . . . . . . . 5-14
Getting Values from a Windows Program . . . . . . . . . . . 5-15
Closing a DDE Connection . . . . . . . . . . . . . . . 5-15
Closing all DDE Connections . . . . . . . . . . . . . . . 5-16
Extending the DISPLAY ARRAY Statement . . . . . . . . . . . 5-17
Returning Key Code Values . . . . . . . . . . . . . . . . . 5-18
Returning Key Codes from P Code . . . . . . . . . . . . . 5-19

vi Four J’s Business Development Language User Guide

Returning Key Codes from C Functions . . . . . . . . . . . . 5-20
Creating a Custom Character Filter. . . . . . . . . . . . . . 5-21
Starting a UNIX Emulator . . . . . . . . . . . . . . . . . . 5-22
Starting Windows Applications . . . . . . . . . . . . . . . . 5-22
Using Input Statement Functions . . . . . . . . . . . . . . . . 5-23
Returning a Value if a Field has been Modified . . . . . . . . . . 5-23
Returning the Name of a Field . . . . . . . . . . . . . . . 5-25
Returning the Value of a Field . . . . . . . . . . . . . . . 5-26
Setting the Value in a Field . . . . . . . . . . . . . . . . 5-26
Displaying a Row at a Given Line in a Screen Array . . . . . . . . 5-26
Closing the Application Window. . . . . . . . . . . . . . . . 5-30
Terminating Applications . . . . . . . . . . . . . . . . . . 5-31
FORM and LINE Mode with the RUN Instruction . . . . . . . . . . 5-31
SQL Syntax Support . . . . . . . . . . . . . . . . . . . 5-33
Support For Embedded SQL 7.3 Syntax . . . . . . . . . . . 5-33
Support for Preparable SQL Statements . . . . . . . . . . . 5-35
Year 2000 Support . . . . . . . . . . . . . . . . . . . . 5-38
Legacy Support for DBCENTURY . . . . . . . . . . . . 5-40
CENTURY Field Attribute . . . . . . . . . . . . . . . . 5-41
CENTURY Display Attribute in PROMPT Statements . . . . . . . 5-42
Screen Array Management. . . . . . . . . . . . . . . . . . 5-42
Data Editing in Screen Arrays . . . . . . . . . . . . . . . 5-42
CANCEL INSERT Keywords . . . . . . . . . . . . . . 5-43
CANCEL DELETE Keywords. . . . . . . . . . . . . . 5-44
INSERT ROW Attribute. . . . . . . . . . . . . . . . 5-45
DELETE ROW Attribute . . . . . . . . . . . . . . . 5-45
CURRENT ROW DISPLAY Attribute . . . . . . . . . . . . 5-46
COUNT Attribute . . . . . . . . . . . . . . . . . . . 5-47
MAXCOUNT Attribute . . . . . . . . . . . . . . . . . 5-47
FGL_SCR_SIZE( ) Built-In Function . . . . . . . . . . . . . 5-48
Report Output Configuration . . . . . . . . . . . . . . . . . 5-50
START REPORT . . . . . . . . . . . . . . . . . . . 5-50

Table of contents vii

String Concatenation Operator . . . . . . . . . . . . . . . . 5-51
Equal Comparison Operator Synonym . . . . . . . . . . . . . 5-52
Hiding the Comment Line . . . . . . . . . . . . . . . . . 5-53
Editing Multibyte Data in 4GL Forms . . . . . . . . . . . . . 5-53
Commenting 4GL Extensions for Compatibility . . . . . . . . . . 5-56
Informix BOOLEAN Data Type Support. . . . . . . . . . . . . 5-57
Retrieving FGLPROFILE settings . . . . . . . . . . . . . . . 5-59
Retrieving the Current Process Identifier . . . . . . . . . . . . . 5-60

Form Extensions
In This Chapter . . . . . . . . . . . . . . . . . . . . . 6-3
List Boxes . . . . . . . . . . . . . . . . . . . . . . 6-4
Buttons . . . . . . . . . . . . . . . . . . . . . . . 6-6
Bitmaps . . . . . . . . . . . . . . . . . . . . . . . 6-11
Check Boxes . . . . . . . . . . . . . . . . . . . . . 6-12
Radio Buttons . . . . . . . . . . . . . . . . . . . . . 6-14
Button Fields . . . . . . . . . . . . . . . . . . . . . 6-15
Combo Box Fields. . . . . . . . . . . . . . . . . . . . 6-16
Scrolling Fields. . . . . . . . . . . . . . . . . . . . . 6-17
Folder Tabs . . . . . . . . . . . . . . . . . . . . . . 6-17
Form Labels. . . . . . . . . . . . . . . . . . . . . . 6-19
Password Fields . . . . . . . . . . . . . . . . . . . . 6-21

Graphical Extensions
In This Chapter . . . . . . . . . . . . . . . . . . . . . 7-3
Display Extensions . . . . . . . . . . . . . . . . . . . 7-3
Four J’s Business Development Language Library Initialization . . . . 7-3
Check User Interface Type . . . . . . . . . . . . . . . . 7-3
Checking for Graphical User Interface usage . . . . . . . . . . 7-5
Checking for Windows Client Mode . . . . . . . . . . . . . 7-6
Window-Management Functions . . . . . . . . . . . . . . . 7-8
Setting the Size of the Application Container . . . . . . . . . . 7-8
Setting the Title of the Application Container . . . . . . . . . . 7-8
Retrieving Information from a Field . . . . . . . . . . . . . 7-9
Retrieving Application Window Properties. . . . . . . . . . . 7-10
Setting the Current Window . . . . . . . . . . . . . . . 7-11

viii Four J’s Business Development Language User Guide

Closing a Window by Name . . . . . . . . . . . . . . . . 7-12
Clearing a Window by Name. . . . . . . . . . . . . . . . 7-12
Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . 7-13
Creating an Interactive Message Box . . . . . . . . . . . . . 7-13
Displaying an Interactive Message Box . . . . . . . . . . . . 7-14
Formatting Text in a Message Box . . . . . . . . . . . . . . 7-15
Entering a Field Value into a Message Box . . . . . . . . . . . 7-16
Multiple Document Interface (MDI) Support . . . . . . . . . . . . 7-17
MDI Configuration. . . . . . . . . . . . . . . . . . . 7-18
Toolbars . . . . . . . . . . . . . . . . . . . . . . . 7-19
Statusbars . . . . . . . . . . . . . . . . . . . . . . . 7-24
Output redirection. . . . . . . . . . . . . . . . . . . . . 7-25
Drawing Extensions . . . . . . . . . . . . . . . . . . . . 7-29
Mouse-Management Functions . . . . . . . . . . . . . . . 7-29
Returning a Value After a Left Mouse Click . . . . . . . . . 7-29
Returning a Value After a Right Mouse Click . . . . . . . . . 7-30
Remove Key Binding . . . . . . . . . . . . . . . . 7-30
Defining the Drawing Area . . . . . . . . . . . . . . . . 7-30
Initializing the Drawing Function . . . . . . . . . . . . . . 7-31
Selecting a Drawing Area. . . . . . . . . . . . . . . . . 7-32
Selecting a Drawing Color . . . . . . . . . . . . . . . . 7-33
Specifying the Text Insertion Point . . . . . . . . . . . . . . 7-33
Changing Line Colors . . . . . . . . . . . . . . . . . . 7-34
Setting Line Width . . . . . . . . . . . . . . . . . . . 7-34
Clearing the Draw Function . . . . . . . . . . . . . . . . 7-34
Drawing Rectangles . . . . . . . . . . . . . . . . . . 7-35
Drawing an Oval . . . . . . . . . . . . . . . . . . . 7-35
Drawing a Circle . . . . . . . . . . . . . . . . . . . 7-36
Drawing a Line . . . . . . . . . . . . . . . . . . . . 7-36
Drawing Text . . . . . . . . . . . . . . . . . . . . 7-37
Drawing an Arc . . . . . . . . . . . . . . . . . . . . 7-37
Drawing a Polygon. . . . . . . . . . . . . . . . . . . 7-38

The Configuration File

In This Chapter . . . . . . . . . . . . . . . . . . . . . 8-4
The Four J’s Business Develpoment Language Configuration File . . . . . 8-4
Global Configuration File . . . . . . . . . . . . . . . . 8-4
User Configuration File . . . . . . . . . . . . . . . . . 8-5

Table of contents ix
Program Configuration File . . . . . . . . . . . . . . . 8-5
General Configuration . . . . . . . . . . . . . . . . . . 8-6
Runtime Configuration . . . . . . . . . . . . . . . . . . 8-6
General . . . . . . . . . . . . . . . . . . . . . . 8-6
UNIX . . . . . . . . . . . . . . . . . . . . . . 8-9
Microsoft Windows . . . . . . . . . . . . . . . . . . 8-10
License Configuration . . . . . . . . . . . . . . . . . . 8-13
General . . . . . . . . . . . . . . . . . . . . . . 8-13
UNIX . . . . . . . . . . . . . . . . . . . . . . 8-16
Graphical User Interface . . . . . . . . . . . . . . . . . . 8-17
General . . . . . . . . . . . . . . . . . . . . . . 8-17
fglrun.interface . . . . . . . . . . . . . . . . . . 8-17
Graphical Daemon Autostart . . . . . . . . . . . . . . . 8-19
Menu . . . . . . . . . . . . . . . . . . . . . . 8-20
Screen GUI Settings . . . . . . . . . . . . . . . . . . 8-21
Key GUI Settings. . . . . . . . . . . . . . . . . . . 8-24
Windows GUI Settings . . . . . . . . . . . . . . . . . 8-30
Local Editing Settings . . . . . . . . . . . . . . . . . 8-31
Cut, Copy, and Paste Feature Settings . . . . . . . . . . . . 8-32
Memory Mapping Settings . . . . . . . . . . . . . . . . . 8-34

The Debugger
In This Chapter . . . . . . . . . . . . . . . . . . . . . 9-3
Requirements . . . . . . . . . . . . . . . . . . . . . 9-3
Installation . . . . . . . . . . . . . . . . . . . . . . 9-3
Starting the Debugger. . . . . . . . . . . . . . . . . . . 9-4
Invoking debug mode on running applications . . . . . . . . . . . 9-4
UNIX platforms . . . . . . . . . . . . . . . . . . . 9-4
Microsoft Windows Platforms. . . . . . . . . . . . . . . 9-5
Debugger Commands . . . . . . . . . . . . . . . . . . . 9-5

Environment Variables

Hints, Tips and Workarounds

Global Language Support

x Four J’s Business Development Language User Guide
Introduction

Introduction

In This Introduction . . . . . . . . . . . . . . . . . . . 3
About This Guide . . . . . . . . . . . . . . . . . . . . 3
Organization of This Guide . . . . . . . . . . . . . . . 3
Audience . . . . . . . . . . . . . . . . . . . . . 5
Software Dependencies . . . . . . . . . . . . . . . . . 5

Documentation Conventions . . . . . . . . . . . . . . . . 5
Typographical Conventions . . . . . . . . . . . . . . . 6
Icon Conventions . . . . . . . . . . . . . . . . . . 7

Additional Documentation . . . . . . . . . . . . . . . . . 7
Four J’s Welcomes Your Comments . . . . . . . . . . . . . . 8
2 Four J’s Business Development Language User Guide
In This Introduction
This introduction provides an overview of the information in this guide and describes
the conventions used.

About This Guide

The Four J’s Business Development Language User Guide describes how to develop
4GL applications on UNIX and Windows NT/2K, and then deploy them, in either
graphical or text mode, on various platforms, such as Windows 9x, Windows NT,
Windows 2K and X11 Window System clients.

This guide assumes that you already have a complete set of INFORMIX-4GL manuals,
such as the INFORMIX-4GL Reference and the appropriate SQL manuals. This guide
should be used in addition to the 4GL manuals.

Organization of This Guide

This guide includes the following chapters:
• Chapter 1, “Product Description,” introduces Four J’s BDL.
• Chapter 2, “Installation,” describes how to install Four J’s BDL on both
UNIX and Windows.
• Chapter 3, “First Steps,” explains how to set environment variables and
compile a simple program in Four J’s BDL.
• Chapter 4, “Using the Compiler,” describes how to compile various types of
files and how to compile to P code or C code.
• Chapter 5, “Language Extensions,” describes the added features that extend
the functionality of 4GL. These features do not affect the graphical interface.

Introduction 3
Organization of This Guide

• Chapter 6, “Form Extensions,” describes the added features that extend the
functionality of 4GL forms.
• Chapter 7, “Graphical Extensions,” describes the added features that extend
the functionality of 4GL. These features affect the graphical user interface
(GUI).
• Chapter 8, “The Configuration File,” describes how to edit the fglprofile
file to change the behavior of the Four J’s BDL compiler .
• Chapter 9, “The Debugger,” describes how to use the Four J’s BDL
Debugger.
• Appendix A, “Environment Variables,” describes the environment
variables needed to use Four J’s BDL.
• Appendix B, “Hints, Tips and Workarounds,” provides workarounds for
common problems that may be encountered.
• Appendix C, “Global Language Support,” describes how to use GLS
features with Four J’s BDL.

4 Four J’s Business Development Language User Guide

Audience

Audience
This guide is written for all Four J’s BDL users.

This guide is written with the assumption that you have the following background:

• A thorough knowledge of INFORMIX-4GL

• Some experience working with relational databases or exposure to database
concepts

Software Dependencies
This guide is written with the assumption that you are using a supported database
server.

Documentation Conventions
This section describes the conventions that this guide uses.

The following conventions are covered:

• Typographical conventions
• Icon conventions

Introduction 5
Typographical Conventions

Typographical Conventions
This guide uses the following conventions to introduce new terms, illustrate screen
displays, describe command syntax, and so forth.

Convention Meaning

KEYWORD All primary elements in a programming language statement

(keywords) appear in uppercase letters in a serif font.

italics Within text, new terms and emphasized words appear in italics. Within
italics syntax and code examples, variable values that you are to specify
italics appear in italics.

boldface Names of program entities (such as classes, events, and tables),

boldface environment variables, file and pathnames, and interface elements
(such as icons, menu items, and buttons) appear in boldface.

monospace Information that the product displays and information that you enter
monospace appear in a monospace typeface.

KEYSTROKE Keys that you are to press appear in uppercase letters in a sans serif
font.

? This symbol indicates a menu item. For example, “Choose

Tools?Options” means choose the Options item from the Tools
menu.

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.

6 Four J’s Business Development Language User Guide

Icon Conventions

Icon Conventions
Comment icons identify three types of information, as the following table describes.
This information always appears in italics.

Icon Label Description

Warning: Identifies paragraphs that contain vital instructions,

cautions, or critical information

Important: Identifies paragraphs that contain significant information

about the feature or operation that is being described

Tip: Identifies paragraphs that offer additional details or

shortcuts for the functionality that is being described

Additional Documentation
Four J’s BDL documentation is provided in a variety of formats:

• Portable Document Format (PDF). The Four J’s Business Development

Language User Guide is available as an Adobe PDF file that can be read
with the free Acrobat Reader.
• Release notes. Release notes are located in the /release directory where the
product is installed. Please examine these files because they contain vital
information about application and performance issues.
• HTML files. Additional documentation about Web server configuration and
product extensions is provided in supplementary HTML files.

Introduction 7
Four J’s Welcomes Your Comments

Four J’s 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 clarifications that
you would find useful. Include the following information:

• The name and version of the guide that you are using
• Any comments that you have about the guide
• Your name, address, and phone number

Write to us at the following address:

Four J’s Development Tools.

Documentation Team
3,rue Gabrielle Colette
67800 Bischheim
France

If you prefer to send electronic mail, our address is:

[email protected]

We appreciate your suggestions.

8 Four J’s Business Development Language User Guide

Chapter

Product Description
1
In This Chapter . . . . . . . . . . . . . . . . . . . . 1-3
Introducing Four J’s Business Development Language . . . . . . . . 1-3
Windows Interface . . . . . . . . . . . . . . . . . . 1-3
Web Interface . . . . . . . . . . . . . . . . . . . . 1-4
Text Interface . . . . . . . . . . . . . . . . . . . . 1-4
GLS Support . . . . . . . . . . . . . . . . . . . . 1-4
Three-Tier Client/Server Architecture . . . . . . . . . . . . 1-5
Client Example . . . . . . . . . . . . . . . . . . 1-6
Architecture . . . . . . . . . . . . . . . . . . . 1-6
Differences Between Four J’s Business Development Language and 4GL . . 1-7
Features Summary . . . . . . . . . . . . . . . . . . . 1-12
1-2 Four J’s Business Development Language User Guide
In This Chapter
This chapter introduces the features of Four J’s BDL, including differences between
the standard 4GL compiler and the Four J’s BDL compiler.

Introducing Four J’s Business Development

Language
Four J’s BDL allows you to recompile 4GL source code, transforming existing text-
based applications into a thin client/server system that can display 4GL applications
with a graphical user interface (GUI).

In addition to standard 4GL routines, applications can be enhanced for display with a
GUI using Four J’s BDL extensions - for example check boxes or list boxes can be
added to your GUI by enhancing the current 4GL source code.

Windows Interface
The GUI is displayed by a graphics server running on the client. The graphics server
can be either X11 or a Windows version of the Tcl/Tk software, called WTK, which
is provided with the Four J’s BDL software.

Web Interface
You can also provide a GUI for Four J’s BDL applications through any compatible
Web browser. You can use either HTML or Java to do this. To use HTML, you run a
daemon provided with the Four J’s BDL software that converts the output of your
program to HTML. To use Java, you must have a Web server that supports servlets.
The 4GL source code does not need to be converted to use either method.

Introduction 1-3
Text Interface

Text Interface
Programs may also be executed in ASCII mode. This means that users access your
programs in the same way they would access standard 4GL programs, that is by
logging on to the same computer that runs the programs. The ease by which you can
change modes allows you to control the migration rate of your client computers.

GLS Support
Four J’s BDL supports Informix Global Language Support (GLS). The GLS feature
allows Informix database servers to handle different languages, cultural conventions,
and code sets.

While Four J’s BDL is fully compliant with Informix GLS, there are some restric-
tions. You cannot use GLS with the Four J’s BDL HTML or X11 Clients.

1-4 Four J’s Business Development Language User Guide

Three-Tier Client/Server Architecture

Three-Tier Client/Server Architecture

By a simple recompilation with Four J’s BDL, the 4GL sources are transformed into
a three-tier client/server system, as Figure 1-1 shows. This system facilitates
migration from ASCII-based terminals to systems with a GUI.
Figure 1-1
4GL Three-Tier
Client/Server
Architecture

Four J’s BDL uses this architecture in the following ways:

• The 4GL application is compiled in P code and deployed on the application

server where a Dynamic Virtual Machine ( DVM) is installed.
• Four J’s BDL can access a database server anywhere on the network.
• Four J’s BDL can be accessed by ASCII, X11, or Windows clients.
• A Web server can access Four J’s BDL.
• The Java and HTML clients can access Four J’s BDL through the Web
Server.

Introduction 1-5
Three-Tier Client/Server Architecture

Client Example
Figure 1-2 shows a 4GL application before and after it was converted to a Windows
client.
Figure 1-2
4GL Application Converted
to a Windows Client

4GL ASCII

...recompiled using Four J’s BDL for a Windows client.

Architecture
The application server can be a UNIX server or a Windows NT/2K computer. In a
typical installation, Four J’s BDL is installed on the application server (either the
development or runtime version) with the 4GL programs. The database server is
usually installed on this same computer, but this is not required.

The client computers can be X11 compliant interfaces or Windows computers. Each
client has its own Four J’s BDL daemon that handles the GUI aspects of 4GL
applications.

1-6 Four J’s Business Development Language User Guide

Differences Between Four J’s Business Development Language

Differences Between Four J’s Business

Development Language and 4GL
Four J’s BDL is based on the features in Version 7.3 of 4GL. However, it is possible
to compile programs created with older versions of 4GL.

The following list summarizes the differences between Four J’s BDL and 4GL:

• Initialization of variables. The 4GL compiler initializes global variables

with empty structures, whereas the Four J’s BDL compiler initializes them
to null.
The 4GL compiler initializes decimal variables to 0, and the Four J’s BDL
compiler sets them to null, like INFORMIX-4GL Rapid Development Sys-
tem (RDS).
• Datetime. With the instruction CURRENT, the Four J’s BDL compiler
manages three positions of the fraction part, whereas 4GL manages only
two.
• Arrays. If you call for an index that is out of range of an array, the Four J’s
BDL compiler can either stop execution of the program with a runtime error,
or it can return NULL for the non-existing elements of an array and continue
with the program. Use the entry fglrun.arrayIgnoreRangeError in the
configuration files if you want the compiler to continue execution.
• Input array. If you use an INPUT or INPUT ARRAY instruction in Four J’s
BDL, be sure that at least one field is not declared as noentry.
The following example shows an INPUT ARRAY instruction where Informix
accepts all fields declared as noentry:
INPUT ARRAY rec_array WITHOUT DEFAULTS FROM scr_arr.*
BEFORE ROW
EXIT INPUT
END INPUT

Introduction 1-7
Differences Between Four J’s Business Development Language and 4GL

• Mouse usage. Creating graphical applications in Four J’s BDL makes it

possible to use the mouse to move from one field to another directly,
without passing by an intermediate field in the INPUT statement. Therefore,
an entry exists in the configuration file that allows you to execute all the
intermediate triggers when users move from one field to another. This entry
is named dialog.fieldOrder.
Right-clicks and double-clicks are also supported. The following two
entries in the configuration files accommodate these mouse actions:
gui.key.doubleClick.left= "key" # default is KEY_accept
gui.key.click.right = "key" # default is F36
• Reports. Normally, if any value that is part of an aggregate function
(avg,sum,…) is NULL, the result of the function is also NULL. In Four J’s
BDL reports, you can have aggregates return 0 in such a case by setting the
report.aggregateZero entry in the configuration file.
Also in reports, it is possible to use a global variable to define the PAGE
LENGTH of a report. Simply set this variable to the desired value before call-
ing the START REPORT statement.
• Menu. In Four J’s BDL, the 4GL menu can be displayed either on the top of
the application window or on the right side of the screen on top of the hot
key buttons. Use the menu.style entry in the configuration file to choose the
position of the menu in the application window.
It is also possible to have a bitmap displayed on menu buttons. To do so, pre-
cede the label by the character @, for example:
menu "blabla"
command "@stop.bmp"
exit program
command "hello"
exit menu
end menu
• The sqlexit statement. The sqlexit() function provides a way of termi-
nating the sqlexec process. It must be invoked as follows:
CALL --#sql::
sqlexit()
You must restart the sqlexec process before the next SQL statement. Use the
following statement:
DATABASE databasename

1-8 Four J’s Business Development Language User Guide

Differences Between Four J’s Business Development Language

• PROMPT. In Four J’s BDL, the 4GL PROMPT statement waits for an answer
in the graphical window at the prompt line if the graphical window is
opened first. If no graphical window is open before the PROMPT statement
is executed, the prompt is made in the ASCII terminal, for example:
MAIN
DEFINE C CHAR (1)
DISPLAY "Hello"
PROMPT "Press any key" FOR CHAR C
END MAIN
•• In the previous example, PROMPT is executed in the terminal and in
terminal mode even if you are in graphical mod
•• The following example shows how to execute PROMPT in graphical
mode:
MAIN
DEFINE C CHAR (1)
DISPLAY "Hello" AT 5,5
PROMPT "Press any key" FOR CHAR C
END MAIN

Introduction 1-9
Differences Between Four J’s Business Development Language and 4GL

• Informix Universal Server BOOLEAN. 4GL uses the INTEGER data type
for boolean expressions. INFORMIX Universal Server introduces a new
BOOLEAN data type which actually is a CHAR(1) where the "t" and "f"
values represent the TRUE and FALSE boolean values. These
"BOOLEAN" values cannot be used directly in 4GL boolean expressions.
Here is an example of 4GL code that raises a data type conversion error :
# Prerequisite : The database holds a table defined as :
# CREATE TABLE tab1 ( col1 BOOLEAN )
#
DATABASE stores
MAIN
DEFINE vbool INTEGER
LET vbool = ( 1 = 0 )
INSERT INTO tab1 VALUES( vbool )
END MAIN

-9634 No such cast.

The specified cast does not exist. Use the CREATE CAST
statement to define the cast.
The following functions are provided to convert INFORMIX Universal
Server "BOOLEAN" values to 4GL INTEGER booleans:
•• fgl_charbool_to_intbool
Converts an Informix Universal Server BOOLEAN value ("t", "f") to a
4GL INTEGER value (TRUE, FALSE). The function returns NULL If
the given value does not match "T", "t", "F" or "f".
•• fgl_intbool_to_charbool
Converts a 4GL INTEGER value to a CHAR(1) value to be stored in a
BOOLEAN column of an Informix Universal Server table. The func-
tion returns NULL if the given value is NULL.

The above example can be written as follows:

# Prerequisite : The database holds a table defined as :
# CREATE TABLE tab1 ( col1 BOOLEAN )
#
DATABASE stores
MAIN
DEFINE vbool CHAR(1)
LET vbool = fgl_intbool_to_charbool( 1 = 0 )
INSERT INTO tab1 VALUES( vbool )
END MAIN
On the other hand, when you retrieve a BOOLEAN values from the data-
base, you can convert that value with the fgl_charbool_to_intbool( ) as in
the following example :

1-10 Four J’s Business Development Language User Guide

Differences Between Four J’s Business Development Language

# Prerequisite : The database holds a table defined as :

# CREATE TABLE tab1 ( col1 BOOLEAN )
# and fglschema has been executed with the "-c" flag.
#
DATABASE stores
MAIN
DEFINE rtab1 RECORD LIKE tab1.*
SELECT * INTO rtab1.* FROM tab1
IF fgl_charbool_to_intbool( rtab1.col1 ) THEN
DISPLAY "TRUE"
ELSE
DISPLAY "FALSE"
END IF
END MAIN

Introduction 1-11
Features Summary

Features Summary
The following list summarizes the features that have been added to the standard 4GL
language:

• Global Language Support. Allows Informix database servers to handle

different languages, cultural conventions, and code sets.
• Open Database Interface Support. The ODI allows 4GL applications to
connect to non-Informix databases such as Oracle, IBM DB2, SQL Server.
• SQL Grammar extension. Supports 4GL SQL syntax for versions 4.1 to 7.3
• 4GL Debugger. The runtime system inclues an integrated 4GL debugger
which provides a set of commands compatible to the Informix 4GL
debugger.
• Channel functions. Channel functions are a way to use I/O streams.
Channel extensions provide access to the files and the processes of the
system without using the RUN statement. Your application requires fewer
resources than with the RUN statement and allows you to communicate with
pipes with other applications.
• Windows DDE functions. DDE functions call a Windows application from
4GL. With this extension, you can invoke a Windows application and send
or receive data to or from it. To use this functionality, the program must be
executed on a Windows computer or on a UNIX computer but from a
Windows front end.
• Drawing functions. This set of functions allows you to draw basic shapes
in 4GL in an area defined like an array.
• Dialog box functions. You can create different types of dialog boxes. You
can add a title and window size independently from your source specifi-
cation. You can also draw items or dynamically change the labels on
buttons.
• Field Management Functions. These functions have been added to
manage fields from the 4GL source code. You can, for example, find out the
name of a field, set or get the value dynamically, and set or get the cursor
position in a field.
• Window Management Functions. Like the field functions, these functions
have been added to manage the different windows in your 4GL applications.
You can use them to find out the name of the current window, its size, and
other characteristics.

1-12 Four J’s Business Development Language User Guide

Features Summary

• Extended DISPLAY ARRAY statement. The DISPLAY ARRAY statement

accepts [BEFORE|AFTER|EXIT|CONTINUE] DISPLAY and
[BEFORE|AFTER] ROW statements.
• Extended INPUT ARRAY. Allows the INSERT and DELETE keys to be
enabled or disabled independently of each other.
• fgl_system() function. You can run a program using a UNIX terminal to
display the output. Even if the running Four J’s BDL program has been
started without a visible terminal with the Windows front end, the UNIX
terminal will be started and placed in the foreground during the execution of
the external program. Then it will be placed in the background or disappear
when the program using it is finished.
• fgl_getkey() function. This function waits for a keystroke and returns the
key code of a pressed key.
• Concatenation operator. Provides support for the || concatenation string
operator.
• Dynamic Report Configuration. Allows the size of the report page and the
report destination to be specified when a report starts.
• The report pager. A pager has been written that allows you to scroll reports
that appear on the screen. For wide reports of more than 80 columns, you
can also scroll horizontally. The correct sizing of the vertical scrollbar
requires a PAGE TRAILER. To switch to the previous or next page, click a
button.
To manage interruption of the display, the int_flag has to be tested after
every OUTPUT TO REPORT instruction.
The pager.42e command starts the graphical editor used to display reports
in C code. The fglpager command starts the graphical editor used to display
reports in P code. The same pager can be used from the UNIX prompt for the
C version:
$ pager.42e [filename]
or on Windows NT for the P-code version:
$ fglpager [filename]

Introduction 1-13
Features Summary

The fglpager command has the same functionality as pager.42e except that:
•• you can only scroll 10 pages backwards.
•• you can see all pages, but you must specify a database name as
parameter -d dbname because the page uses temporary tables.
Reports in 4GL programs can also use temporary tables. Because they
use a lot of space, you must first call the function
fgl_report_use_temptable() to enable them. Otherwise, you can see
only 10 pages backwards.
•• If you execute the report with FGLGUI=0, the pager will display all the
report without stopping after each page.
• Toolbars. A toolbar can be added to the top of the screen to represent
frequently used commands.
• Status bar. Allows the status of certain keys to be displayed on the status
bar.
• Folder Tabs. Allows multiple screen forms to be displayed using folder
tabs (appear similar to Windows folder tabs) enabling the user to easily
navigate between multiple screens. .
• Splash screen. Allows a splash screen to be displayed after starting an
application. .
• Local Editing. Enables the client to wait until an entire value has been
entered into a field before submitting the information to the application
server. .
• Cut and Paste. Enables standard cut and paste functionality within the
Windows Client or X11 Client. .
• Screen record without size. With fglform (.per compiler), you are not
required to specify the screen record size, but if you do not specify the size,
you will not have a scrollbar.
• Terminate handler. Allows a standard close window option to appear in
the upper-right corner of a GUI window. Alt+F4 will also close the window.
• Terminate signal. Allows a 4GL application to send a terminate signal
(available only for UNIX).
• Character filter. You can define conversion files to be used for characters
on the GUI.

For more information, see the INFORMIX-4GL Reference Manual. 4GL 7.3

1-14 Four J’s Business Development Language User Guide

Chapter

Installation
2
In This Chapter . . . . . . . . . . . . . . . . . . . . 2-3
Before Installing Four J’s Business Development Language . . . . . . 2-3
Release Notes . . . . . . . . . . . . . . . . . . . . . 2-3
Hardware requirements . . . . . . . . . . . . . . . . . . 2-3
Disk Space Requirement . . . . . . . . . . . . . . . . 2-3

Software requirements . . . . . . . . . . . . . . . . . . 2-4

Licensing the Product . . . . . . . . . . . . . . . . . . 2-4
Supported Operating Systems . . . . . . . . . . . . . . . . 2-5
Upgrading Four J's BDL . . . . . . . . . . . . . . . . . . 2-6
Product Information Viewer . . . . . . . . . . . . . . . . 2-6
Product Directory Structure . . . . . . . . . . . . . . . . . 2-7
Post Installation Tasks . . . . . . . . . . . . . . . . . . 2-8
UNIX installation . . . . . . . . . . . . . . . . . . . . 2-8
Installation Program Requirements . . . . . . . . . . . . . 2-8
TCP/IP Requirements . . . . . . . . . . . . . . . . . 2-8
C/C++ Compiler Requirements . . . . . . . . . . . . . . 2-9
Informix Prerequisites . . . . . . . . . . . . . . . . . 2-9
Prerequisites for GLS . . . . . . . . . . . . . . . . 2-9
Start the Installation on Unix . . . . . . . . . . . . . . . 2-9
Windows installation . . . . . . . . . . . . . . . . . . . 2-10
TCP/IP Requirements . . . . . . . . . . . . . . . . . 2-10
C/C++ Compiler Requirements . . . . . . . . . . . . . . 2-11
Using Windows Front End on the same machine . . . . . . . . . 2-11
Informix Prerequisites . . . . . . . . . . . . . . . . . 2-11
Start the Installation on Windows. . . . . . . . . . . . . . 2-11

2-2 Four J’s Business Development Language User Guide

Before Installing Four J’s Business Development Language

In This Chapter
This chapter describes how to install the Four J’s BDL product. This chapter includes
instructions for installing the application server on either UNIX or Windows NT.

Before Installing Four J’s Business

Development Language
Please read this chapter before installing the Four J’s BDL product. Additional pre-
requisites are listed in the Unix and Windows specific installation sections.

Release Notes
After installation, the Four J’s BDL release notes will be found in $FGLDIR/release
on Unix systems or %FGLDIR%/release on Windows systems. This file contains
important information such as machine specific notes, enhancements and bug
corrections.

Hardware requirements
A network card is required to license a Four J’s BDL installation.

Disk Space Requirement

The Four J’s BDL software needs about 15MB in a temporary directory during instal-
lation and about 20MB after installation. Please ensure you have sufficient free space
on your disk.

Installing Four J’s Business Development Language 2-3

Software requirements

Software requirements
An ANSI compatible C/C++ compiler and linker is required. Common system
modules and libraries such as TCP/IP are also a requirement.

A database server or database client software must be installed along with the C
development kit. If the product is to be licensed via the Four J’s web site, a Web
browser and internet connection will be needed.

See “UNIX installation” on page 2-8 or “Windows installation” on page 2-10 for
more details about required software.

Licensing the Product

During Four J's BDL installation, you will be prompted to license the software. You
will need the license number and license number key supplied with in the Four J's
BDL package, for example:
FAB#B34006FG + GFAS9FD78FDT

To perform a full licensing, you will be prompted for the license number and license
number key and an installation number will be generated. Go to the www.4js.com
web site to get the installation number key (contact your local support if you fail to
get the key from the web site). Finally, enter the installation number key to complete
licensing.

You have 30 days to enter the installation number key. If you cannot get the instal-
lation number key, you will have to complete the licensing manually by using the
following command:

$ fglwrt -k installation_number_key

The following command will show the current installation number:

$ fglwrt -a see

2-4 Four J’s Business Development Language User Guide

Supported Operating Systems

When upgrading Four J's BDL by installing on an existing FGLDIR with a valid
license, you do not have to re-enter the license keys.

An existing license may be dropped using the command:

$ fglwrt -d

and re-entered using:

$ fglwrt -l

Note: Neither the serial number nor the installation number will ever contain the
letter O, only the digit 0 (zero).

Supported Operating Systems

Four J's BDL is available on both UNIX and Windows Platforms:

System Earliest supported version

IBM AIX 4.2

DG/UX (intel) R4.20

HP/UX 10.01
SCO Open Server 5.0.x

SCO Unixware 7.1

Digital UNIX (OSF) 4.0

IRIX (n32) 6.2

Reliant UNIX (SINIX) 5.43

SUN Solaris (sparc) 2.5.1

Installing Four J’s Business Development Language 2-5

Upgrading Four J's BDL

System Earliest supported version

SUN Solaris (intel) 2.6

Dynix/Ptx 4.4.2

Linux glibc 2.1

Windows NT Intel 4 sp3

Refer to the Release Notes in FGLDIR/release or www.4js.com for more details on

supported operating system versions.

Upgrading Four J's BDL

When upgrading the Four J's BDL, it is not necessary to re-enter the license the
product as long the new version is installed into the existing installation directory. To
do this, ensure the FGLDIR environment variable is set to the current installation
directory. Verify the user rights (you should login as the owner of the current
installed files) and ensure all binaries can be overwritten.

Note: When upgrading, all running programs must be stopped, especially the license
server if it is used. If the database development kit has changed, unset the FGLDBS,
FGLLIBSQL and FGLLIBSYS environment variables.

Product Information Viewer

Product information, such as the version number of the product and its components,
can be displayed using the fpi tool.
$ fpi -l

2-6 Four J’s Business Development Language User Guide

Product Directory Structure

Product Directory Structure

This section describes the directories created during the installation process. The root
is referenced by the FGLDIR environment variable.

Path Description

bin Four J's BDL executable files.

bmp Pictures included with in 4GL programs for X11 clients.

defaults Program-specific FGLPROFILE configuration files.

demo Four J's BDL demonstration programs.

desi The configuration manager for X11 clients.

etc Configuration files and graphical client resources.

etc/ger Filter for the German alphabet character set.

etc/iso Filter for the ISO character set.

include Include files.

include/f2c Include files for C interfaces.

lib 4GL and DVM Libraries to link a runner.

lock License data files (do not remove!).

msg Compiled messages files.

release Latest documentation (release notes).

src Source files of tools and 4GL libraries.

toolbars Toolbar icons.

Installing Four J’s Business Development Language 2-7

Post Installation Tasks

Post Installation Tasks

After installing the Four J's BDL you may need to perform the following tasks:

• Search the system and database libraries with findlib.sh and create the
environment file.
• Create a P-Code runner with fglmkrun.
• Create the P-Code libraries with rtsinstall.
• Create the C-Code libraries with fglinstall.

UNIX installation
This section describes how to install Four J's BDL on Unix platforms.

Installation Program Requirements

The Four J's BDL installation program is a Bourne shell script. Ensure you have a
compatible Bourne shell interpreter (/bin/sh).

TCP/IP Requirements
A development version of TCP/IP must exist on the development server. Check your
operating system manuals to be sure this module is installed. For example, on SCO
UNIX System 3.2, the library libsocket.a must be present.

2-8 Four J’s Business Development Language User Guide

C/C++ Compiler Requirements

C/C++ Compiler Requirements

You must have an ANSI compatible C compiler and linker on the development
computer. The C compiler is used during the installation to create a runner by linking
operating system, database client and Four J's BDL runtime libraries together. Four
J's recommends installing the latest GNU C compiler for this product. If you want to
use a native C compiler, check that it conforms to ANSI standards. ANSI-compatible
C compilers accept the -c flag to produce object files and the -o flag to produce
executable files. You can define the C compiler for Four J's BDL with the FGLCC
environment variable. When using INFORMIX ESQL/C, you can set the C compiler
with the INFORMIXC environment variable to force the esql compiler to use your C
compiler.

Informix Prerequisites
Four J's recommends the latest ESQL/C software when using Informix. You can
download Informix Client SDK from the Informix Web site:
http://www.informix.com

Prerequisites for GLS

For GLS, the Informix Client SDK 2.01 (or later) must be installed before Four J's
BDL. If you do not need the GLS libraries, the Client SDK is recommended but not
mandatory.

Start the Installation on Unix

The Four J's BDL product is provided in an auto-extractable shell script. Distribution
files and installation program are provided in the same file. The name of the package
includes the operating system type and version. Ensure the package name corre-
sponds to your system before starting the installation program.

The installation program needs options. You can display the installation program
options using the -h option:

$ /bin/sh fjs-f4gl-3.10.2a-aix0430.sh -h

Installing Four J’s Business Development Language 2-9

Windows installation

The installation program determines the operating system and checks that all the
system requirements are met before starting to copy the product files to your disk.

To perform the installation steps:

1. Log in as the super-user (root)

2. Start the installation program with the -i option:
$ /bin/sh fjs-f4gl-3.10.2a-aix0430.sh -i
3. Follow the instructions

If you are using Informix, you will be prompted to install Four J's BDL with GLS
enhancements during the installation, . You should only install the GLS enhancement
if you are planning on using the GLS features. The GLS enhancement will install
additional files - for more information on GLS, see Appendix C, “Global Language
Support.”

Warning: You must have the Client SDK 2.01 (or later) installed and the database
server running to install the GLS features.

Windows installation
This section describes how to install Four J's BDL on Microsoft Windows platforms.

TCP/IP Requirements
Warning: Only the Microsoft TCP/IP stack is supported. Problems may occur with
other TCP/IP stacks.

2-10 Four J’s Business Development Language User Guide

C/C++ Compiler Requirements

C/C++ Compiler Requirements

The only fully supported C compiler is Microsoft Visual C++ 4.0 or later. Both CL
and LINK programs are needed. Ensure you have these tools on your Windows
machine.

Using Windows Front End on the same machine

If you plan to use the Windows Front End, we strongly recommend installing the
WTK before the Four J's BDL as the BDL installation program detects the WTK and
creates shortcuts to automatically start the WTK when executing 4gl programs.

Informix Prerequisites
You must have at least an ESQL/C development package installed to create P-Code
runners for Informix. The Informix ESQL/C package must be compatible with the
Informix database you want to access.

Warning: Four J's strongly recommends to use Informix ESQL/C Version 7.20.TE1
or higher as Version 7.20.TD1 may cause system instability on Windows NT 4.0. You
can download the latest Informix Client SDK without charge from the Informix web
site. For more information, see the Informix web site.

Start the Installation on Windows

The Four J's BDL product is provided in a standard Windows setup program. Distri-
bution files and installation program are provided in the same file. The name of the
package includes the software version and the Windows operating system version.
Ensure the package name corresponds to your Windows system before starting the
installation program.

To perform the installation steps:

1. Log in as the Administrator

2. Start the installation program:
fjs-f4gl-3.10.2a-wnt0304.exe
3. Follow the instructions

Installing Four J’s Business Development Language 2-11

Start the Installation on Windows

2-12 Four J’s Business Development Language User Guide

Chapter

First Steps
3
In This Chapter . . . . . . . . . . . . . . . . . . . . 3-3
Setting the Environment Variables . . . . . . . . . . . . . . 3-3
Compiling a Simple Program . . . . . . . . . . . . . . . . 3-4
Writing the Source Code . . . . . . . . . . . . . . . . 3-5
Compiling the Source Code . . . . . . . . . . . . . . . 3-6
Compiling to P Code . . . . . . . . . . . . . . . . 3-6
Compiling to C Code . . . . . . . . . . . . . . . . 3-6
Compiling the Form-Specification File . . . . . . . . . . . . 3-7
Viewing the Four J’s Business Development Language Application . . . 3-8
3-2 Four J’s Business Development Language User Guide
In This Chapter
This chapter explains how to set environment variables and compile a simple
program in Four J’s BDL.

Setting the Environment Variables

During installation, a file is created that sets the environment for your configuration.
This file is located in the directory where you installed Four J’s BDL and is named
envcomp.

The first task is to set up correct environment variables. To do this, execute the
envcomp script located in the $FGLDIR directory. For instance, if the compiler is
installed in the /usr/fgl2c directory, type the following Bourne shell commands:
$ cd /usr/fgl2c
$ . ./envcomp

This script adds the following environment variables.

Variable Description

FGLDIR The directory specified during the installation for Four J’s BDL

INFORMIXDIR The Informix root directory specified during the installation of

Four J’s BDL

FGLDBS Tells the compiler which version of the Informix interface you
installed on your computer

FGLCC Name of the C compiler you want to use

FGLLIBSQL List of the required Informix SQL libraries

(1 of 2)

First Steps 3-3

Compiling a Simple Program

Variable Description

FGLLIBSYS List of the required system libraries

FGLGUI Used only at runtime to specify if the program should be

executed in graphical mode or in ASCII mode

PATH Search path for required files and components. The script adds
the $FGLDIR/bin directory to your PATH

FGLSHELL External shell for linking system tools (CC, GCC), or Informix
tools (ESQL, C4GL) to compile a P-code runner

LD_LIBRARY_PATH Location of shared libraries.

(2 of 2)
This file is a Bourne shell script. If you are using a UNIX C shell you must configure
the file to work on your system. It is a good idea to include it in your user configu-
ration files.

Compiling a Simple Program

This section provides a step-by-step procedure to compile a simple 4GL program with
the Four J’s BDL compiler, which involves these tasks:

• Writing the 4GL source code

• Compiling to P code or C code

After you compile the program, you compile the form-specification file.

3-4 Four J’s Business Development Language User Guide

Writing the Source Code

Writing the Source Code

The first step is to write the 4GL source code for your application. The following
sample program is made of two 4GL modules and one form-specification file.

The first source code file, ex1-1.4gl:

MAIN
CALL fgl_init4js()
OPEN WINDOW w1 AT 1,1 WITH 24 ROWS, 80 COLUMNS
OPEN FORM frm1 FROM "ex1-1"
DISPLAY FORM frm1
MENU "F4GL"
COMMAND "Message box"
CALL message_box()
COMMAND "Exit"
EXIT MENU
END MENU
END MAIN

The second 4GL source code file, ex1-2.4gl:

FUNCTION message_box()
DEFINE f01,f02,bt1 CHAR(20)
INPUT BY NAME bt1,f01,f02;
CALL fgl_winmessage(f01,f02,bt1)
END FUNCTION

The form-specification file, ex1-1.per:

DATABASE FORMONLY
SCREEN {

Icon [bt1] Title[01]

Message[f02]

ATTRIBUTES
f01 = formonly.f01;
f02 = formonly.f02;
bt1 = formonly.bt1,widget="RADIO", default="info",
config="info Info exclamation Exclamation question
Question stop Stop";

All the strings between the double quotes are case sensitive.

First Steps 3-5

Compiling the Source Code

Compiling the Source Code

The next step is to compile this 4GL source code. You can compile to either P code
or C code.

Compiling to P Code
P code has many advantages over C code. The main advantages of using P code are:

• you compile it once and then you can run the same compiled modules on
every computer on which a Four J’s BDL runtime package is installed.
• all the new 4GL features are implemented in P code only.

To compile ex1-1 to P code, change to the directory where you created the ex1-1.4gl
and ex1-1.per files. Check that your environment variable is correctly set:
$ echo $FGLDIR

This statement should return the directory where you installed Four J’s BDL. Also
check if the $FGLDIR/bin directory is included in the PATH variable:
$ echo $PATH

Now compile the .4gl source-code files into modules with the .42m extension. Use
the fgl2p script calling the fglcomp program:
$ fgl2p ex1-1.4gl
$ fgl2p ex1-2.4gl

After compiling, you must link the two .42m modules together into a file with the
.42r extension. Use the fgl2p script again, but this time it calls the fgllink program:
$ fgl2p -o ex1.42r ex1-1.42m ex1-2.42m

The resulting ex1.42r file does not contain any executable code. This file is a hash
table that contains calls to the functions included in the .42m modules. It is absolutely
necessary to keep these modules accessible at runtime.

Compiling to C Code
You can compile the sample program to C code. However, C code is only available
for UNIX platforms. To compile to C code, use fgl2c instead of fgl2p.

3-6 Four J’s Business Development Language User Guide

Compiling the Form-Specification File

In addition, you need the following: a C compiler, a linker, and two environment
variables (FGLLIBSYS and FGLLIBSQL). These two environment variables are
defined at install time in the envcomp file located in the $FGLDIR directory.

Check that they are correctly set:

$ echo $FGLLIBSYS
$ echo $FGLLIBSQL

These two commands should return a list of system libraries and Informix libraries.

To compile the .4gl source-code files into object files with the .42o extension, the .4gl
files are first compiled into .42c files by the fglcomp program and then are compiled
by your C compiler into .42o object files:
$ fgl2c -c ex1-1.4gl
$ fgl2c -c ex1-2.4gl

In this case, you should use the -c flag.

Next, link the object files, your system libraries, the Four J’s BDL libraries, and the
Informix libraries together into a single executable file with the .42e extension:
$ fgl2c -o ex1.42e ex1-1.42o ex1-2.42o

Compiling the Form-Specification File

Form files are compiled with the fglform compiler. Compiled forms can be used by
both P-code and C-code programs. To compile the form-specification file ex1-1.per,
type the following:
$ fglform ex1-1.per

The result of the compilation is a .42f file. In this case, you get the file ex1-1.42f.

First Steps 3-7

Viewing the Four J’s Business Development Language Application

Viewing the Four J’s Business Development Language

Application
The Four J’s Four J’s BDL application can be viewed using a client interface. The
following illustration shows how the application will look when viewed using the
X11 Client.
Figure 3-1
Application
Displayed
Using the X11 Client

3-8 Four J’s Business Development Language User Guide

Chapter

Using the Compiler

4
In This Chapter . . . . . . . . . . . . . . . . . . . . 4-4
Setting Environment Variables for the Compiler . . . . . . . . . . 4-4
Compiling Form-Specification Files and Help Message Files . . . . . . 4-5
Compiling Form-Specification Files. . . . . . . . . . . . . 4-5
Compiling Help Message Files . . . . . . . . . . . . . . 4-6

Generating a Database Schema File . . . . . . . . . . . . . . 4-6

Compiling to P Code . . . . . . . . . . . . . . . . . . . 4-7
Overview of a P-Code Example . . . . . . . . . . . . . . 4-7
Compiling Source Files to Linkable Modules . . . . . . . . 4-8
Linking Modules Together to Create P Code . . . . . . . . . 4-8
Using C Functions in 4GL Applications . . . . . . . . . . . 4-9
Compatibility Problems with C . . . . . . . . . . . . . 4-9
Support for Variable Varameters in C Functions. . . . . . . . 4-9
Linking C Functions with the P-Code Runner . . . . . . . . 4-11
The C extension file . . . . . . . . . . . . . . . . 4-14
Example . . . . . . . . . . . . . . . . . . . . 4-14
Compiling to C Code . . . . . . . . . . . . . . . . . . . 4-19
Overview of a C-Code Example . . . . . . . . . . . . . . 4-19
Compiling Source Files to Linkable Modules . . . . . . . . 4-20
Linking Modules to Create C-Code Libraries . . . . . . . . 4-20
Using C Functions in 4GL Applications . . . . . . . . . . . 4-21
Linking C Functions for Use in C-Code Compilations . . . . . . 4-21
Compilation Tools. . . . . . . . . . . . . . . . . . . . 4-26
Main Compilation Tools . . . . . . . . . . . . . . . . 4-26
fgl2p . . . . . . . . . . . . . . . . . . . . . 4-27
fgl2c . . . . . . . . . . . . . . . . . . . . . 4-29
fglcomp . . . . . . . . . . . . . . . . . . . . 4-32
fgllink . . . . . . . . . . . . . . . . . . . . . 4-33
fglform . . . . . . . . . . . . . . . . . . . . 4-35
fglschema . . . . . . . . . . . . . . . . . . . . 4-36
fgldbsch . . . . . . . . . . . . . . . . . . . . 4-36
fglmkmsg . . . . . . . . . . . . . . . . . . . . 4-37
ar42o . . . . . . . . . . . . . . . . . . . . . 4-38
findlib.sh . . . . . . . . . . . . . . . . . . . . 4-39
Configuration Tools . . . . . . . . . . . . . . . . . . 4-41
fglmode . . . . . . . . . . . . . . . . . . . . 4-42
licencef4gl . . . . . . . . . . . . . . . . . . . 4-44
fglfontsel, fglfontsel.42e . . . . . . . . . . . . . . . 4-45
Miscellaneous Programs and Scripts . . . . . . . . . . . . . 4-46
rtsinstall, fglinstall . . . . . . . . . . . . . . . . . 4-47
fglpager, pager.42e . . . . . . . . . . . . . . . . . 4-47
fglX11d . . . . . . . . . . . . . . . . . . . . 4-48
fglWrt . . . . . . . . . . . . . . . . . . . . . 4-48

4-2 Four J’s Business Development Language User Guide

Using the Compiler 4-3
Setting Environment Variables for the Compiler

In This Chapter
This chapter contains all the syntax needed for compiling 4GL programs into Four J’s
BDL programs using P code or C code. It also explains how to add calls from 4GL
programs to C programs and how to make calls from C programs to 4GL programs.

This chapter covers the following topics:

• Setting environment variables for the compiler

• Compiling 4GL form specification files and help message files
• Generating a database schema file
• Compiling to P code
• Compiling to C code
• Creating a P-code runner with fglmkrun
• Compilation tools

Setting Environment Variables for the Compiler

The first task is to set up correct environment variables. To do this, execute the
envcomp script located in the $FGLDIR directory. This shell script was created
during installation and it sets up the main environment variables required to use Four
J’s BDL.

For instance, if the compiler is installed in the /usr/fgl2c directory, type the following
Bourne shell commands:
$ cd /usr/fgl2c
$ . ./envcomp

Important: You should include a call to this shell script in your session startup file
(.login or .profile on most UNIX platforms).

You can control the behavior of the Four J’s BDL compiler with configuration files.
For more information, see Chapter 8, “The Configuration File.”

4-4 Four J’s Business Development Manual User Guide

Compiling Form-Specification Files and Help Message Files

Compiling Form-Specification Files and Help

Message Files
This section describes how to compile the form-specification files and help message
files that your 4GL applications use.

Compiling Form-Specification Files

You need to recompile 4GL forms into a Four J’s BDL format. The compiled form
files can be used with applications compiled to either P code or C code.

The tool to compile forms is fglform. The extension of the compiled .per files is .42f.
The compilation syntax is as follows:
$ fglform formname{.per}

This command compiles the form-specification file named formname.per into

formname.42f. The .per extension is not mandatory on the command line.

Important: Because you might need to recompile forms on a computer other than
your development computer, the fglform compiler is installed with theFour J’s BDL
runtime package.

Using the Four J’s Business Development Language Compiler 4-5

Compiling Help Message Files

Compiling Help Message Files

You need to recompile the 4GL help message files into a Four J’s BDL format. The
help message compiler, named fglmkmsg, is similar to the Informix mkmessage
compiler. The compilation syntax is as follows:
$ fglmkmsg input_file output_file

The following command decompiles the file and the output is written to the standard
output:
$ fglmkmsg -r compiled_file

Generating a Database Schema File

To compile 4GL programs using a default database for DEFINE ... LIKE and
VALIDATE instructions, you need to generate a database schema file. Run the
following command in a directory and environment where you have access to your
database (for instance, you should be able to access the database with the Informix
tools INFORMIX-SQL and DB-Access):
$ fglschema database_name

The file database_name.sch is generated. If needed, two other files are generated:
databasename.att and databasename.val. These files contain informations from the
syscolatt and syscolval tables.

The FGLDBPATH environment variable can be used to define the path to the direc-
tories containing database schema files.

Important: While no changes are required to the database before using Four J’s
BDL, a schema file must be generated each time that the database structure changes.

4-6 Four J’s Business Development Manual User Guide

Compiling to P Code

Compiling to P Code
This section describes how to compile a sample 4GL program to linkable modules
and how to link those modules together to create an executable program. It also
describes how to use C functions in your applications.

P code is hardware-independent pseudo-executable code. The same P code can be

executed on any operating system on which Four J’s BDL is installed. Furthermore,
P code allows you to use many of the improvements added to 4GL that are not
available for use with C code.

Overview of a P-Code Example

In this section, you will compile the following 4GL program named example.4gl:
MAIN
DISPLAY "Hello World"
END MAIN

Before executing this program, you need to compile the code and then link the needed
modules and the P-code runner. Figure 4-1 shows the complete compilation schema.
Figure 4-1
4GL
fgl2p -c P-code module
P-Code
Source Compilation
fgl2p -o Schema
Main p-code module
4GL +
+
Source fgl2p -c P-code module P-code
runner P-code modules
4GL
Source fgl2p -c P-code module

C
Source fglmkrun P-code runner

The name of the Four J’s BDL P-code compiler is fgl2p. This tool compiles 4GL
sources into P-code executables or libraries.

Using the Four J’s Business Development Language Compiler 4-7

Overview of a P-Code Example

Compiling Source Files to Linkable Modules

By convention, the following extensions are used for filenames:

• .4gl for the source-code files

• .42m for the compiled modules
• .42r for the file resulting from the linking of compiled modules

The syntax for the first step of the compilation, compiling 4GL source code into
linkable modules is:
$ fgl2p 4gl_source_code.4gl

For example:
$ fgl2p example.4gl

This line compiles the 4GL source-code file example.4gl to the module
example.42m.

Linking Modules Together to Create P Code

The following syntax links the compiled .42m modules together to create an
executable or library. This link also checks for C functions included in the runner
(see“Linking C Functions with the P-Code Runner” on page 4-11) that the FGLRUN
environment variable specified.
$ fgl2p –o executable.42r module1.42m [module2.42m] …

This line links the compiled modules module1.42m and module2.42m into the
executable.42r. The following line links the compiled modules module1.42m and
module2.42m into the library library.42x:
$ fgl2p –o library.42x module1.42m [module2.42m] …

This library can be used as an object module file when linking applications that use
calls to functions defined in the library.

At runtime, all modules linked together must be located in a directory specified by

the FGLLDPATH environment variable.

4-8 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

The .42m modules are linked together into the .42r hash table that contains cross-
references to all functions and variables used in the 4GL application. Thus, all
unresolved or faulty references (for instance, missing functions, or function calls with
an incorrect number of parameters or return values) are detected at link time instead
of at runtime.

At runtime, only the .42r and .42m modules that contain the MAIN section are loaded
into memory. All other .42m modules are loaded when needed. Every module and all
library modules appear only once in the application. This can lead to a significant
reduction in the size of the P-code modules constructing the application.

Using C Functions in 4GL Applications

This section describes a strategy for using C functions in an application.

Compatibility Problems with C

Using C functions in 4GL applications can cause problems when the application is
ported to a platform other than the one used to develop it. For example, problems may
be experienced when porting an application from UNIX to Windows NT and vice
versa. Problems can also occur when too many specific calls to system features are
used.

In both cases, try to reduce calls to C functions and system commands to reduce the
risk of problems when porting to other platforms.

Four J’s BDL contains extra functions and features that allow calls to most of the C
functions and calls to system features to be avoided. For a description of the new
extensions to the 4GL language, see Chapter 5, “Language Extensions.”

Support for Variable Varameters in C Functions.

The compiler can be used with the '-z file' option to support variable parameters
and/or variable returned values for C function calls.

Defining the C interface

A C function interface is described in the C extension file with the UsrFunction
structure as follows:
{ "4gl_function_name", C_function_name, nb_params, nb_returns }

Using the Four J’s Business Development Language Compiler 4-9

Using C Functions in 4GL Applications

Where:

• 4gl_function_name = function name in the 4GL program

• C_function_name = function name in the C module
• nb_params = number of parameters
• nb_returns = number of return values

To define a variable number of parameters or returned values, the nb_params or

nb_returns must be set to -1.
Example:
UsrFunction usrFunctions[2]={
{ "tst1_cfunc", tst1_cfunc, 0, 0 },
{ "tst2_cfunc", tst2_cfunc, -1, 0 },
{ "tst3_cfunc", tst3_cfunc, -1, 2 },
{ 0,0,0,0 }
};

Compiling with the -z option

First, a list of C functions defined in the runtime system must be created. The virtual
machine provides the '-z' option to generate the list of User's C functions imple-
mented in the runtime system

For example:
$ fglrun -z
sum -1 1
cos 1 1
sin 1 1

Store this list in a file. The file will be used by the compiler with the -z option, to
check all the C function calls:
$ fglrun -z > myfuncs.out
$ fgl2p -z myfuncs.out -o myprog.42r module.4gl

4-10 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

Linking C Functions with the P-Code Runner

Because the low-level instruction set is defined in the P-code runner, and because C
functions have only a low-level implementation (that is, they do not change the 4GL
syntax), they must be linked with the runner at its creation.

To use C functions in a 4GL program, you must:

• define the C functions in a C-extension file.

• compile your C files and the C-extension file.
• build the runner with the C files.

The fglmkrun shell script allows you to generate a specific runner with your own C
functions. For more information, you can view the output of fglmkrun. Different
options are provided, run fglmkrun -h for more details

Viewing Sample fglmkrun Output

You can see what was done during fglmkrun execution. The output displays the
following information:

• The name and location of the created P-code runner

• The compiler/linker used by the script to build the P-code runner (for
example, esql, gcc, cc, c4gl, and so on)
• The list of the additional flags and libraries added to the command line
• The current value of $INFORMIXDIR
• The version of the database interface.
• The memory mapping used is the system built-in or an emulation. For infor-
mation on memory mapping see “Memory Mapping Settings” on page 8-34.
• The list of all files added to the compiler
In most instances, these are C-function source files called from the 4GL
source code.

Using the Four J’s Business Development Language Compiler 4-11

Using C Functions in 4GL Applications

To view the P-code runner output, execute fglmkrun. The following information
appears:
The runner was successfully linked with the following options:
Runner name : /usr/fgl2c/bin/fglrun
Language Support Library : ASCII
Compiler : esql
Additional flags/libs : None
Informix dir : /informix
Database interface : ix914 (/usr/fgl2c/lib/libix914.a)
Memory mapping : System built in
User extensions : None

Important: Be sure that the environment is correct before executing fglmkrun. If

necessary, run the findlib.sh shell script and use the resulting shell script.

Building a Statically Linked Runner

To build a statically linked P-code runner named myrun using the Client SDK,
Version 2.10, and a C-function file name file.c (assuming the prototype of these
functions are defined in the file $FGLDIR/lib/fglExt.c), execute fglmkrun with the
following command:
$ fglmkrun -d ix914 -add -static $FGLDIR/lib/fglExt.c file.c -o myrun

The following output appears:

The runner was successfully linked with the following options:
Runner name : myrun
Language support library: ASCII
Compiler : esql
Additional flags/libs : -static
Informix dir : /ix/informix.csdk
Database interface : ix914 (/work/pl/fgl2c/lib/libix914.a)
Memory mapping : System built in
User extensions : Yes
/work/pl/fgl2c/lib/fglExt.c
file.c

4-12 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

Details About fglmkrun

You can use the following options when executing fglmkrun:
Syntax fglmkrun options [ext]

Options

-V Display fglmkrun version information.

-h Display help message with a list of fglmkrun options.

-vb Verbose mode displays the compilation line used and fglmkrun output.

-o name Output to name, default=fglrun. This symbolic link is to the default

runner created either in the $FGLDIR/bin/gls directory if the flag -gls is
set and in $FGLDIR/bin/ascii if it is not set.

-d dbver Database interface version, default=ix410

n ix210 : Informix 2.10
n ix410 : Informix 4.10
n ix501 : Informix 5.01
n ix711 : Informix 7.11
n ix914 : Informix 9.1x and higher

-sh prog External shell for linking (esql, c4gl, and so on). The fglmkrun script can
use the system tools (cc, gcc) or Informix tools (esql, c4gl) to compile a
P-code runner. For system tools, the required Informix libraries and
system libraries have to be set with the findlib.sh script. For Informix
tools, the Informix tools automatically find the libraries. Default value is
CC.

-add "other" Add other system libraries or flags to link. The -add flag sends the
specified parameter to the compiler building the runner. The argument
will not be interpreted by the fglmkrun script.

ext List of user extension modules. This can be anything else that is to be
compiled and linked with the runner such as libraries, C files, object files,
and so forth.

-gls Set this option is you want to use the GLS language support library. To
create a runner with GLS support, you need the Client SDK 2.01 (or later)
database interface. If the -gls flag is not specified, a runner handling only
the ASCII charset is created.

Using the Four J’s Business Development Language Compiler 4-13

Using C Functions in 4GL Applications

You must specify the -d ix711 option if programs are to run with Informix 7.x
database servers. Alternatively, you can set the environment variable FGLDBS to
ix711.

The C extension file

The following source shows the default extension file $FGLDIR/lib/fglExt.c:
#include "f2c/fglExt.h"
#include "f2c/r_c.h"
UsrData usrData[]={
{ 0, 0 }
};
UsrFunction usrFunctions[]={
{0,0,0,0 }
};

The two arrays usrData and usrFunctions must always be present in the file. The
last record of each array must be a line with all the elements set to 0. The usrData
array contains the name of the global variables modified by your C programs, and
usrFunctions contains the name of the C functions called from the 4GL modules.

You can copy the file $FGLDIR/lib/fglExt.c and adapt it to your own needs.

Example
This first example is a simple call to a C function in a 4GL module.

First create your C file (example.c):

#include <stdio.h>
int fncc1(int n)
{
printf ("This a C file.");
return 0;
}

Compile it with your C compiler:

$ cc -c example.c

4-14 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

Before any modification, copy fglExt.c into your working directory to make it
available for all users. Then edit fglExt.c and update it with the following definitions:
#include "f2c/fglExt.h"
UsrData usrData[]={
{ 0, 0 }
};
int fncc1(int n);
UsrFunction usrFunctions[]={
{"fncc1",fncc1,0,0},
{0,0,0,0 }
};

Now build the new runner with the following command:

$ fglmkrun -o newrunner example.o fglExt.c

This command builds a runner (the link between the Informix libraries, system
libraries, Four J’s BDL libraries, and the file example.o) named newrunner. This
runner is for 4.x Informix databases.

Do not give your new runner the same name as one of the files located in the current
directory. When you have created the new runner, you can create the 4GL example
(example.4gl) with the following lines:
MAIN
CALL fncc1()
END MAIN

Compile the .4gl file with the following command:

$ fgl2p –c example.42m example.4gl

And link your object file example.42m to example.42r with the following
commands:
$ FGLRUN=newrunner
$ export FGLRUN
$ fgl2p -o example.42r example.42m

The shell script fgl2p uses the value of the FGLRUN environment variable to
determine which runner to link with. If you do not set the FGLRUN environment
variable before you link your 4GL program, the compiler will generate an error
because the fncc1 function was undefined.

Now you can execute your P-code executable with the following command:
$ newrunner example.42r

Using the Four J’s Business Development Language Compiler 4-15

Using C Functions in 4GL Applications

Calling 4GL from C

Building on what you know about calling a C function from a 4GL module, you can
call 4GL from a C function. Use the fgl_call macro in your C programs, as follows:
fgl_call(funcname,nbparam)

where funcname is the name of the 4GL function to call (CHAR), and nbparam is the
number of parameters (INTEGER). This function returns the number of return values
(INTEGER).

The parameters must be pushed on the stack before the call, and the return values
must be popped from the stack after returning. The 4GL function must be declared
external in the C-extension file. Update the C file as follows:
#include <stdio.h>
#include <f2c/fglExt.h>
int fncc1(int n)
{
fgl_call( fnc2,0);
return 0;
}

Compile the C file using the following command:

$ cc -c example.c -I$FGLDIR/include

Then build the new runner with the following command line:
$ fglmkrun -o newrunner example.o fglMyExt.c

Then update the 4GL example:

MAIN
CALL fncc1()
END MAIN
FUNCTION fnc2()
DISPLAY "You are in 4gl function"
END FUNCTION

Compile it with fgl2p:

$ FGLRUN=newrunner
$ export FGLRUN
$ fgl2p –c example.42m example.4gl
$ fgl2p –o example.42r example.42m

Now you can run it with the new runner:

$ newrunner example.42r

4-16 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

Modifying 4GL Global Variables From C Functions

The last step is to modify 4GL global variables in C functions. Every variable must
be defined in the C file as well as in the C-extension file used to build the specific
runner. The C-extension file also contains the definitions of the C functions.

The global 4GL variables are internally redefined, so you have to use the CNAME
macro to reference them in your C files that contain your C functions.

Furthermore, every variable must be defined as external to the C module with its
corresponding type. Use the following syntax:
#define variable_name_in_4gl CNAME(variable_name_in_4gl)

where variable_name_in_4gl is the name of the variable in 4GL.

The following example shows a file that contains the C functions called from 4GL:
#include <stdio.h>
#include "f2c/fglExt.h"
#define var CNAME(var)
#define res CNAME(res)
extern int var;
extern char res[101];
int fncc1(int n)
{
printf("%s %d\n", res, var);
return 0;
}

Compile the C file with the following command:

$ cc -c example.o -I$FGLDIR/include

The code is:

#include "f2c/fglExt.h"
GLOB_CHAR(res,100);
GLOB_INT(var);

UsrData usrData[]={
GLOB(var),
GLOB(res),
{ 0, 0 }
};
int fncc1(int n);
UsrFunction usrFunctions[]={
{ "fncc1",fncc1,0,0 },
{0,0,0,0 }
};

Using the Four J’s Business Development Language Compiler 4-17

Using C Functions in 4GL Applications

Create the new runner:

$ fglmkrun -o newrunner example.o fglExt.c

The following table shows the supported data types.

CHAR GLOB_CHAR
GLOB_VARCHAR

SMALLINT GLOB_SMALLINT

INTEGER GLOB_INT

SMALLFLOAT GLOB_SMALLFLOAT

FLOAT GLOB_FLOAT

DECIMAL GLOB_DECIMAL

MONEY GLOB_MONEY

DATE GLOB_DATE

The list of supported data types can also be found in the file
$FGLDIR/include/f2c/fglExt.h.

Global RECORD and ARRAY statements are not allowed.

Adapt your 4GL example as follows:

GLOBALS
DEFINE var INTEGER,
res CHAR(100)
END GLOBALS
MAIN
LET var = 15
LET res = "The result is "
CALL fncc1()
END MAIN

Compile it with fgl2p and run it with the new runner:

$ fgl2p -o example.42r example.4gl
$ newrunner example.42r

4-18 Four J’s Business Development Manual User Guide

Compiling to C Code

Compiling to C Code
While Four J’s BDL allows you to compile 4GL programs to C code, consider
compiling to P code rather than C code. With C-code compilation, you must
recompile the whole program whenever you change the execution platform, whereas
with P code, you only need to rebuild your runner. In addition, P code does not
execute significantly slower than C code.

Overview of a C-Code Example

In this section, you compile the following 4GL program named example.4gl to C
code:
MAIN
DISPLAY "Hello World"
END MAIN

Before you execute this program, you first need to compile it and then link all the
needed modules. Figure 4-2 shows the complete compilation schema.
Figure 4-2
4GL C-Code
Source fgl2c -c C code module Compilation
Schema
4GL fgl2c -o
Source fgl2c -c C code module Executable

4GL
Source fgl2c -c C code module

C
Source $FGLCC -c C object files

System Libraries
+
Informix Libraries

The name of the Four J’s BDL C-code compiler is fgl2c. This tool compiles the 4GL
source code into C-code executables or into libraries.

Using the Four J’s Business Development Language Compiler 4-19

Overview of a C-Code Example

Compiling Source Files to Linkable Modules

The following conventions are used for the filename extensions:

• .4gl for the source-code files

• .42o for the compiled modules
• .42e for the file resulting from the linking of compiled modules, system
libraries, and P-code libraries

The following syntax is the first step of the compilation, which compiles 4GL source
code into linkable modules:
$ fgl2c –c 4gl_source_code.4gl

For example:
$ fgl2c –c example.4gl

This line compiles the 4GL source-code file example.4gl to the module
example.42o.

Linking Modules to Create C-Code Libraries

The following syntax links the compiled .42o modules together to create the
executable:
$ fgl2c –o executable.42e module1.42o module2.42o

This line links the compiled modules module1.42o and module2.42o into the
executable.42e.

The procedure to create C-code libraries is a little different from that for creating
P-code libraries. To build the C-code libraries, you must use the ar42o tool. The
syntax of ar42o is:
$ ar42o -rv libname.a module1.42o module2.42o

This line uses the UNIX ar command to create the library named libname.a made of
the compiled modules module1.42o and module2.42o. This library can be used as
an object module file when linking applications that use calls to functions defined in
the library. For more information on ar, read the ar man page on your UNIX system.

4-20 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

Using C Functions in 4GL Applications

This section describes a strategy for using C functions in your applications and gives
you a step-by-step example.

Linking C Functions for Use in C-Code Compilations

With C code, the C functions are linked in the same manner as any other modules
during the application link phase. You just have to follow a few rules to successfully
call C functions from 4GL applications and vice versa.

With C code, in order to call a C function from a 4GL application, you do not need a
C-extension file to create the relationship between the name of the C function and the
name of the 4GL function. But you have to call a macro named CFACE defined in the
f2c/r_c.h header file. You will also have to include the f2c/r_c.h header file at the
beginning of your C files. Use the following syntax to call the macro:
CFACE (C_function_name,
param_count,
returned_count)

The following table describes the elements of this command.

Element Description

C_function_name Name of the C function

param_count Number of parameters transmitted to the function

returned_count Number of values returned by the function

Use this macro for all C functions called from 4GL applications. Include the f2c/r_c.h
header file in all the C files that call this macro.

If you want to use the same source files to compile your applications, either with Four
J’s BDL or with the 4GL compilers, use conditional compiling, as in the following
example:
#ifdef fourjs
#include <f2c/r_c.h>
#endif

Using the Four J’s Business Development Language Compiler 4-21

Using C Functions in 4GL Applications

The following example shows a 4GL application that calls a C function named mainc.
The 4GL source-code file is named exCCode.4gl and contains the following code:
MAIN
CALL mainc()
END MAIN

The C source file is named exc.c and contains the following code:
#ifdef fourjs
#include <f2c/r_c.h>/* This is the header file defining the CFACE macro */
#endif
#include <stdio.h>
int mainc(int n)
{
printf ("hello from C !!");
return 0;
}
CFACE(mainc,0,0) /* Macro needed for every function call from 4GL */

Now compile the two previous files with the following commands:
$ cc –c exc.o exc.c –D Informix –I$FGLDIR/include
$ fgl2c –c exCCode.42o exCCode.4gl

Next, link the compiled modules, the system libraries, and the Informix development
libraries together with the fgl2c shell script:
$ fgl2c –o exc.42e exc.o exCCode.42o

To call 4GL functions from a C function, use the fgl_call macro. This macro is also
defined in the f2c/r_c.h header file. The syntax is as follows:
fgl_call(4GL_function_namee,param_count )

The following table describes the elements of this command.

Element Description

4GL_function_name Name of the 4GL function

param_count Number of parameters transmitted to the function

The following example shows a 4GL function that calls a C function, which, in turn,
calls another 4GL function. This example is made of two 4GL modules and one C file.

4-22 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

The first 4GL module is exCCode.4gl:

MAIN
DEFINE word CHAR(60)
OPEN WINDOW w1 AT 1,1 WITH 20 ROWS, 50 COLUMNS ATTRIBUTES(BORDER)
LET word = "How are you?"
CALL mainc(word)
SLEEP 3
CLOSE WINDOW w1
END MAIN

The second 4GL module is fnCCode.4gl:

FUNCTION fncc1(word)
DEFINE word CHAR(60)
IF word = "How are you?" THEN
DISPLAY "Very fine and you?" AT 10, 1
END IF
END FUNCTION

The C file is exc.c:

#ifdef fourjs
#include <f2c/r_c.h>
#endif
#include <stdio.h>
int mainc (int n)
{
CHAR word[13];
popquote(word, 13);
pushquote(word, 13);
fgl_call(fncc1, 1);
return 0;
}
CFACE(mainc, 1, 0)

The C statements popquote, pushquote, pop[…] and push[…] are working exactly
as with INFORMIX-4GL compilers.

Next, compile these three files:

$ cc –c exc.o exc.c –D Informix –I$FGLDIR/include
$ fgl2c –c exCCode.4gl
$ fgl2c –c fnCCode.4gl

Link the three object modules, the system libraries, and the Informix libraries
together:
$ fgl2c –o exCCode.42e exCCode.42o fnCCode.42o exc.o

Run the example by typing:

$ exCCode.42e

Using the Four J’s Business Development Language Compiler 4-23

Using C Functions in 4GL Applications

The next step is to share global variables between C functions and 4GL functions. The
definition process for global variables is exactly the same as when you compile your
program in C code or in P code, except that no
C-extension file is needed. The syntax of the CNAME macro is:
#define variable_name_in_4gl CNAME(variable_name_in_4gl

where variable_name_in_4gl is the name of the variable in 4GL.

To illustrate this macro with C-code compilation, you simply modify the previous
example to use a global variable instead of a parameter to exchange the data between
the 4GL functions and the C function.

The first new 4GL module is exCCode.4gl:

GLOBALS
DEFINE word CHAR(12)
END GLOBALS
MAIN
OPEN WINDOW w1 AT 1,1 WITH 20 ROWS, 50 COLUMNS ATTRIBUTES(BORDER)
LET word = "How are you?"
CALL mainc()
SLEEP 3
CLOSE WINDOW w1
END MAIN

The second one is fnCCode.4gl:

GLOBALS
DEFINE word CHAR(12)
END GLOBALS
FUNCTION fncc1()
IF word = "How are you?" THEN
DISPLAY "Very fine and you?" AT 10, 1
END IF
END FUNCTION

4-24 Four J’s Business Development Manual User Guide

Using C Functions in 4GL Applications

The new C function is exc.c:

#ifdef fourjs
#include <f2c/r_c.h>
#define word CNAME(word) /* here is the variable declaration in the C file
*/
#endif
#include <stdio.h>
extern char word[13]; /*here is the prototype of the variable in the C
file */
int mainc(int n)
{
printf("%s\n", word);
fgl_call(fncc1, 0);
return 0;
}
CFACE(mainc, 0, 0)

Now compile these three files:

$ cc -c exc.o exc.c -D Informix -I$FGLDIR/include
$ fgl2c -c exCCode.4gl
$ fgl2c -c fnCCode.4gl

Next, link the three object modules, the system libraries, and the Informix libraries
together:
$ fgl2c -o exCCode.42e exCCode.42o fnCCode.42o exc.o

Using the Four J’s Business Development Language Compiler 4-25

Compilation Tools

Compilation Tools
All the tools you need in order to compile 4GL programs to P code or C code are
located in the /bin subdirectory. These tools are described in the following sections.

Main Compilation Tools

The following table lists the programs you will most often use to compile
applications.

Filename Description

fgl2p Wrapper command to compile and link applications to P code

fgl2c Wrapper command to compile and link applications to C code

fglcomp 4GL compiler

fgllink 4GL program and library linker

fglform Form specification file compiler

fglschema Informix Database Schema extractor

fglmkmsg Message files compiler

fgldbsch Multi-database schema extractor

ar42o Script to create archive files from .42o object files

findlib.sh Script to find all the libraries needed on your system to create P-code
runners or C-code executables

4-26 Four J’s Business Development Manual User Guide

Main Compilation Tools

fgl2p
To see all available options for this command, execute with the -h argument.

The fgl2p command reads source.4gl files and creates a compiled version of each,
with the name source.42m. You can specify any number of source files, in any order.
You can also link the source files together after compilation to create a P-code
executable.
Warning: Some UNIX systems limit the maximum command line length and can
create unexpected errors with very long command lines.

If an error or warning occurs during compilation, the compiler creates a file called
source.err. Look in source.err to find where the error or warning occurred in your
code. If you specify the -M option, errors and warning messages will be sent to the
screen instead of in a file.

You can use the -W with unused, return or all. When using the -W unused option, a
warning will be displayed for every definition of an unused variable in source.4gl
file. Check your code to remove such variables. The flag -W return forces the
compiler to check the number of returned parameters for every 4GL functions used
in the source.4gl file. If a function is called twice with a different number of param-
eters, a warning will be issued. Using the -W all turns both unused and return on.

Use -o out.42r to instruct the compiler to call the linker after compilation of all the
source.4gl files to create the P-code executable named out.42r.

To display the version number of the software, specify the -V option. After
displaying this information the program exits without compiling.

The -E option list the 4GL libraries used when linking the compiled source.4gl to the
P-code executable out.42r. After displaying this information the program exits
without compiling.

Use -S option to display all SQL instructions found during compilation.

When using the -O (letter O) option, the compiler will optimize the size of the
resulting P-code executable. Use this option only if you are using the -o out.42r flag.
When enabling this optimization, the compiler removes unused 4GL functions from
the resulting .42r file. This behavior may lead to the following error at execution
time, when the call to the 4GL function is issued by a C function:
ERROR(-1338):The function '<name>' has not been defined in any
module in the program.

Using the Four J’s Business Development Language Compiler 4-27

Main Compilation Tools

To prevent the 4GL P code linker removing functions only called in C functions and
not from 4GL modules, you can add a dummy 4GL function containing calls to the
4gl functions used by the C modules.

Examples
The following command compiles the file source.4gl into the object module
source.42m:
fgl2p source.4gl

The following command create a P-code executable named source.42r:

fgl2p -o source.42r source1.4gl source2.4gl

4-28 Four J’s Business Development Manual User Guide

Main Compilation Tools

fgl2c
To see all available options for this command, execute with the -h argument.

The fgl2c command reads source.4gl files and creates a compiled version of each,
with the name source.42o. You can specify any number of source files, in any order.
You can also link the source files together after compilation to create a C-code
executable.
Warning: Some UNIX systems limit the maximum command line length and can
create unexpected errors with very long command lines.

If an error or warning occurs during compilation, the compiler creates a file called
source.err. Look in source.err to find where the error or warning occurred in your
code. If you specify the -M option, errors and warning messages will be sent to the
screen instead of in a file.

You can use the -W option with wopt in unused, return or all. When using the -W
unused flag with the compiler, a warning will be displayed for every definition of an
unused variable in source.4gl file. Check your code to remove such variables. The
flag -W return forces the compiler to check the number of returned parameters for
every 4GL functions used in the source.4gl file. If a function is called twice with a
different number of parameters, a warning will be issued. Using the -W all option
turns both unused and return on.
Use -o out.42e to instruct the compiler to call the linker after compilation of all the
source.4gl files to create the c-code executable named out.42e.

To display the version number of the software, specify the -V option. After
displaying this information the program exits without compiling.

The -E option lists the 4GL libraries used when linking the compiled source.4gl to
the C-code executable out.42e. After displaying this information the program exits
without compiling.

Use -S option to display all SQL instructions found during compilation.

You can specify the type of the database interface library used to communicate with
your database server with the -d dblib option. dblib usually corresponds to the
version of Informix-ESQL/C installed. The -d dblib option is set by default to work
with Informix 4.10 libraries. The possible values for dblib are:

• ix210 for Informix libraries 2.10

• ix410 for Informix libraries 4.10

Using the Four J’s Business Development Language Compiler 4-29

Main Compilation Tools

• ix501 for Informix libraries 5.01

• ix711 for Informix libraries 7.11
• ix914 for Informix libraries 9.1x and higher ( Informix-Client SDK )

If you set in your environment the variable FGLDBS to one of these values you do
not need to use the -d dblib option. However, the -d dblib flag will override the
environment variable if it is used in the command line.

You can choose the external linker used to link the compiled source.4gl files together
to the C-code executable, with the -sh program option. You can use either the
Informix-Esql/C compiler or the Informix-C4GL compiler. It is strongly recom-
mended to use the latest Informix-Esql/C compiler available from Informi-Client
SDK. For example to use the esql compiler specify the option -sh esql.

You can also send extra option flags required by the linker used to create the c-code
executable. To tell to the compiler to ignore these options and to only send them to
the linker use the -add other with other as the list of options. As an example, to create
a statically linked c-code executable use:
-add static

To only preprocess the file source.4gl in order to get only the resulting C language
source file named source.42c without compiling it, use the -p option.

To preprocess and compile the file source.4gl use the -c option. Compiling the file
source.4gl creates an object file named source.42o.

If the Informix-Client SDK 2.01 (or later) is used to link the 4GL source files, you
can enable the Global Language Support (see Appendix C, “Global Language
Support”) using the -gls option.

To display the name of the default tool used to link the compiled modules, the list of
the default flags sent to this tool and the list of the linked libraries with the modules
to create the C-code executable, use the option -E.

Examples
The following command compiles the file source.4gl into the object module
source.42o:
fgl2c -c source.4gl

4-30 Four J’s Business Development Manual User Guide

Main Compilation Tools

The following command creates a statically linked c-code executable named

source.42e using the Informix-Client SDK as a compiler with the Global Language
Support enabled:
fgl2c -sh esql \
-gls -add static \
-o source.42r source1.4gl source2.4gl

Using the Four J’s Business Development Language Compiler 4-31

Main Compilation Tools

fglcomp
The command fglcomp is the basic 4GL source compiler. This compiler is used by
the fgl2c and fgl2p tools.

To see all available options for this command, execute with the -h argument.

The compiler can generate both C code and P code from a 4GL source file. Default
is P code generation. Use the -C option to create C code.

Warning: This option will no longer be supported in version 4 of the Four J’s BDL
Compiler.

To display the version number of the software, specify the -V option. After
displaying this information the program exits without compiling.

4-32 Four J’s Business Development Manual User Guide

Main Compilation Tools

fgllink
To see all available options for this command, execute with the -h argument.

This command may be used to link P-code object modules resulting from the compi-
lation of 4GL modules with fgl2p or fglcomp. You can either create a P-code library
or a P-code program (if one of the module includes the definition of the MAIN
function). A P-code library has a .42x file name extension, as a P-code program has
a .42r extension. You may prefer to use the fgl2p wrapper with the option -o instead
of using fgllink.

To specify the name of the P-code program or library, use the -o option. This option
must be followed by the name of the program or library to create.

You must give the list of .42m P-code modules you want to link together to create
the program or the library.

When using the -O (letter O) option, the compiler will optimize the size of the
resulting P-code executable. When enabling this optimization, the compiler removes
unused 4GL functions from the resulting .42r file. This behavior may lead to the
following error at execution time, when the call to the 4GL function was issued by a
C function:
ERROR(-1338):The function '<name>' has not been defined in any
module in the program.

To prevent the 4GL P code linker from removing functions only called in C functions
and not from 4GL modules, you can add a dummy 4GL function containing calls to
the 4gl functions used by the C modules.

To display the version number of the software, specify the -V option. After
displaying this information, the program exits without linking.

Example
The following command links the two compiled modules mod1.42m and mod2.42m
and the library lib1.42x to create the myprog.42r program.
fgllink -o myprog.42r mod1.42m mod2.42m lib1.42x

Note that the previous command is equivalent to:

fgl2p -o myprog.42r mod1.42m mod2.42m lib1.42x

Using the Four J’s Business Development Language Compiler 4-33

Main Compilation Tools

The following command creates a P-code library from two compiled P-code
modules:
fgllink -o mylib.42x mod1.42m mod2.42m

This command is equivalent to:

fgl2p -o mylib.42x mod1.42m mod2.42m

4-34 Four J’s Business Development Manual User Guide

Main Compilation Tools

fglform
To see all available options for this command, execute with the -h argument.

The fglform command reads source.per form specification files and creates a
compiled form file called source.42f.

To compile a form use :

fglform form-name

where form-name is the name of the form specification file with or without the .per
extension. If the compilation is successful, fglform creates a compiled form file
called form-name.42f. If not, fglform instead creates a file named form-name.err.
Look in form-name.err to discover the compilation errors. Make corrections in the
file form-name.per and recompile.
To display the version number of the software, specify the -V option. After
displaying this information, the program exits without compiling.

When compiling a form, fglform sends the following message to the error output:
'form-name.per' form compilation was successful.

You can hide this message using the -s option.

If you are using references to database fields in a form specification file, you need the
database schema file. Use the fglschema tool to generate this file.

Using the Four J’s Business Development Language Compiler 4-35

Main Compilation Tools

fglschema
To see all available options for this command, execute with the -h argument.

The fglschema utility extracts schema information from your database and generates
ASCII schema files. The column types are stored in dbname.sch, the validation rules
are in dbname.val and the attributes in dbname.att. These schema files are required
when you want to compile form specification files that include references to database
fields or 4GL modules containing statements as DEFINE ... LIKE and VALIDATE.

Attributes and validations rules are defined with the Informix upscol utility. These
attributes and validations are stored in the dbname.att and dbname.val files.

The FGLDBPATH environment variable can be used to define the path to the direc-
tories containing database schema files.

To create the schema files, run fglschema followed by the name of your development
database.

To display the version number of the software, specify the -V option. After
displaying this information the program exits without creating schema files .

fglschema handles new Informix Universal Server data types as follows:

• When using fglschema with the -c option BOOLEAN, INT8 and SERIAL8
are converted to CHAR(1) and DECIMAL(19,0) respectively.
• ROW, LIST, MULTISET and SET types are not supported. When
fglschema detects an unsupported data type, a warning is displayed and by
default the table definition is not written to the schema file. This would
result in compilation errors when using instructions as “DEFINE r
RECORD LIKE table.*”. However, you can use the "-r" flag to force
fglschema to write the table definition without the columns created with
unsupported data types.

fgldbsch
The fgldbsch utility is the equivalent to fglshema except that fgldbsh supports
various database servers such as Oracle, DB2, SQL Server. Refer to fglschema
description for generated files.

To see all available options for this command, execute with the -h argument.

4-36 Four J’s Business Development Manual User Guide

Main Compilation Tools

fglmkmsg
The fglmkmsg utility converts ASCII source files that contain user messages into a
format that 4GL programs can use at runtime.

The format of the ASCII source file must be the same as the one used by the
Informix-4GL mkmessage tool. The structure of the message source file is as
follows:
.num
message-text

where .num is a period followed by an integer and message-text is the text of the
message, one or more lines. This file can contain as many messages as you need.

Each help message should be preceded by a line with nothing on it but a period (in
the first column) and a unique integer num. This number will be used to identify the
help message in your 4GL programs. The messsage-text starts on the next line and
continues until he next number line. Each line must end in a RETURN.

Lines beginning with # are considered comment lines, and are ignored by fglmkmsg.

To compile a message source file:

fglmkmsg input_file output_file

Where input-file is an ASCII message source file and output-file is the pathname of
the compiled message file.

The 4GL program looks for the appropriate help message in the help file that you
specify in an OPTIONS statements, using the HELP FILE potion. You can have
several help files, but only one can be in effect at a time.

Using the Four J’s Business Development Language Compiler 4-37

Main Compilation Tools

ar42o
This tool creates C-code archives from 4GL modules compiled into C-code. After
you compiled a 4GL module source.4gl into C-code you get the compiled module
source.42o. If you have more than one module, you may then create an archive and
use it as a library holding commonly needed subroutines. To be able to use ar42o
your development system must have the ar tool installed.

This tool can pass options to the ar library archiver, refer to the ar man page of your
system.

To display the version number of the software, specify the -V option. After
displaying this information, the program exits without linking.

The option -h display a short help message about the tool.

4-38 Four J’s Business Development Manual User Guide

Main Compilation Tools

findlib.sh
This script searches for Informix software configurations in order to create two shell
scripts ( one in Bourne shell and one in C shell syntax ) that setup the environment
variables needed to compile 4GL applications into P-code or C-code and to create a
P-code runner.

Tip: It is often easier to use the tool fglmkrun with the option -sh esql, if you have a
recent version of Informix Esql/C or Informix CSDK than to use findlib.sh.

The option -V returns the version number of the findlib.sh tool and exits.

With option -l, findlib.sh searches for the needed libraries, tools and options to create
a P-code runner or to compile 4GL applications in C-code. This is the default
behavior.

Additionally you can specify the option -o runner to create a default P-code runner.
The name of the created P-code runner will be the one specified after the -o option.

By default the findlib.sh tool uses the Informix c4gl, esql or cfglgo tools to create P-
code runners or to compile 4GL applications into C-code. You can force the
findlib.sh to use another tool with the option -sh. The name of the tool should be
specified just after the -sh option. Findlib.sh can bypass the call of these tools with
the option -max. In this case findlib.sh will try all possible combinations of the
libraries to create a P-code runner or a C-code application.

When you ask for the creation of a runner with the -o option, you may also force the
use of static libraries or shared libraries if they are available. To use static libraries,
use the -tl static option. If you want to create a P-code runner using shared libraries
use the option -tl shared. You can use the -tl option only if the Informix-Esql/C 7.x
(or later) is installed on the development system. You can also ask the findlib.sh tool
to pass optional parameters that are used by the fglmkrun script. All given param-
eters should be between double quotes (“). Without -sh, findlib.sh find and try to
create a p-code runner with the different tools available. For example, if you want to
create a P-code runner with GLS:
findlib.sh -optrun "-gls"

The two shell scripts created are named envcomp ( for Bourne Shell) and
envcomp.csh (for C Shell). You need to execute one of them in your current shell. For
example, with a Bourne Shell use the following Unix command line:
$ . ./envcomp

Using the Four J’s Business Development Language Compiler 4-39

Main Compilation Tools

Note that it is a period followed by a blank character, another period, a slash and the
name of the shell script that need to be executed. The shell script should be in the
current directory when you issue this command.

To test if you environment is correctly configured, see if the FGLDIR variable is

correctly set. If you are using Bourne shell, you may use the command:
$ echo $FGLDIR

The answer of this command should be the directory where the compiler is installed.

SCO Open Server users may also use the -bElf flag to force the use of “-b elf” by the
C compiler. This can create troubles at compilation time and at runtime. You are
strongly advised not to use this option, unless you really know what you are doing.

4-40 Four J’s Business Development Manual User Guide

Configuration Tools

Configuration Tools
The following table lists tools that aid in configuration.

Filename Description

fglmode Tools mode selector (ASCII/GLS) and tools version number checker.

licencef4gl License Installation Program

confdesi Graphical Configuration Manager program

fglfontsel Font selector tool for X11 interfaces (P-code version)

fglfontsel.42e Font selector tool for X11 interfaces (C-code version)

Using the Four J’s Business Development Language Compiler 4-41

Configuration Tools

fglmode
This shell allows the developer to switch between the GLS enabled version of the
compiler and the ASCII only version. For more about GLS refer to the Appendix C,
“Global Language Support”.

The following binaries must exist in the $FGLDIR/bin/gls and the

$FGLDIR/bin/ascii respectively in GLS and ASCII versions :

• fglcomp : The 4GL compiler

• fglX11d : The X11 client daemon
• fglform : The form compiler
• fglmkmsg : The message compiler

The files, either from the gls directory or from the ascii directory, will be linked in
the $FGLDIR/bin directory by the fglmode tool. It can also link a P-code runner if
any. The p code runners are assumed to be named as specified by the $FGLRUN
environment variable, with fglrun as default. If no P-code runner is found, a warning
message will be displayed explaining how to build it.

This shell will only be installed when the gls and ascii directories do exist in
$FGLDIR/bin. That means that it will only be installed if the system supports the
GLS enhancements. In fact, if the INFORMIX libraries featuring the GLS exits for
the platform.

Syntax: fglmode [options]

Where [options] can be:

4-42 Four J’s Business Development Manual User Guide

Configuration Tools

-m mode Set the character string mode (ASCII or GLS)

-l Check the links to binary files

-e check the current environment

-g show the current character string mode

-V display version information

-h display this help

-v list version information for each component

• The -v option will list the version number of all other Four J’s tools
installed.
• If this command is executed without a parameter, the currently used version
will be displayed, and you will be asked if you want to switch to another
one.
• The integrity of the links will be checked before updating to prevent having
links to gls and to ascii at the same time (for example, fgllink pointing to gls
and fglcomp to ascii)
• The existence of all the executables will be checked in both directories gls
and ascii
• If you type fglmode --mode GLS, or fglmode --mode ASCII, then the
switch will be made.
•• --mode GLS means that the GLS version is expected
•• --mode ASCII means that the ASCII is expected
If the runner is not built, the switch will be made anyway, but you will be
asked to build it with the relevant shell and libraries.
• If you type fglmode --mode GLS (or ASCII) and it is already in GLS (or
ASCII) mode, you will be told that you are already in the chosen mode
• If the integrity of the links is not valid, you will be informed and the changes
will be made (if possible) as expected.

Using the Four J’s Business Development Language Compiler 4-43

Configuration Tools

• If the integrity of the existing links is not valid, and it is not possible to
repair, an error will occur (in the same way as when something is missing in
the expected version).

licencef4gl
The tool licencef4gl is used for an easy installation and reinstallation of the license.
A license defines the number of allowed simultaneous users and whether compilation
of 4GL modules is allowed or not.

When installing or changing a currently installed license, the directory

$FGLDIR/lock is removed and recreated with all permissions ( Read, Write and
eXecute ) for all users. This directory contains data stored by the DVM during the
execution of 4GL applications. As removing this directory while applications are
running will crash those applications, it is important to remember to stop all running
4GL applications before changing a license. Every user running 4GL applications
must be able to write data to the $FGLDIR/lock directory which is why premission
must be set to Read Write and eXecute for all users.

This tool must be run by the owner of the files located in the $FGLDIR directory.

If the installation number key was not entered during the installation process, this can
be entered using the option -k key where key is the installation number key received
from your reseller. This procedure must be done during the 30 days following the
original installation
$ licencef4gl -k XXXXXXXXXXXX

To stop all running 4GL applications you canuse the -i option. Using the -i option
removes all internal data located in the$FGLDIR/lock directory and resets the
number of currently connected users to 0.

4-44 Four J’s Business Development Manual User Guide

Configuration Tools

fglfontsel, fglfontsel.42e
fglfontsel is a 4GL application selecting the font for the X11 graphical front-end.
This application is provided in a P-code and a C-code version. To start it using P-
code, run the fglfontsel shell script , to run it using C-code execute fglfontsel.42e.
You can either execute it in graphical or ASCII mode. To execute it in ASCII mode
set the environment variable FGLGUI to 0 (zero) before running the command.
$ FGLGUI=0
$ export FGLGUI
$ fglfontsel

The application will list all available fonts on the system. It will then save your choice
in a file named .fgl2crc and store this file in the home directory of the current user.

Now 4GL applications started in graphical mode using the X11 frontend by this user
will use the selected font.

Using the Four J’s Business Development Language Compiler 4-45

Miscellaneous Programs and Scripts

Miscellaneous Programs and Scripts

This table lists other helpful tools.

Filename Description

rtsinstall P code environment setup program (compiles libs and tools to P code)

fglinstall C code environment setup program (compiles libs and tools to C code)

fglpager Script to start the graphical editor used to display reports (P-code version)

pager.42e Graphical editor used to display reports (C-code version)

fglX11d Graphical daemon for the X11 interfaces

fglWrt Main license program

4-46 Four J’s Business Development Manual User Guide

Miscellaneous Programs and Scripts

rtsinstall, fglinstall
The rtsinstall and fglinstall shell scripts are only available in the development
version of the compiler. Both can be automatically executed by the installation
program, if required by the user. These tools compile all messages files, 4GL libraries
and additional tools like fglpager and fglfontsel. rtsinstall prepares a P-code
environment and fglinstall prepares a C-code environment. The 4GL source code of
the libraries and tools are located in the $FGLDIR/src and the message files are stored
in the $FGLDIR/msg subdirectories. If you change one of these files, you can easily
recompile everything with either the rtsinstall or the fglinstall command depending
on whether your applications are to be compiled in P-code or C-code

fglpager, pager.42e
The fglpager and the pager.42e are 4GL applications provided to scroll forwards and
backwards in report output redirected to the screen. Reports using more than 80
columns can be scrolled horizontally. The correct sizing of the vertical scrollbar
requires a PAGE TRAILER. To manage interruption of the display, the int_flag has to
be tested after every OUTPUT TO REPORT instruction. The pager.42e command
starts the graphical editor used to display reports in C-code. The fglpager command
starts the graphical editor used to display reports in P code.

The pager can be used from the UNIX prompt for the C version:
$ pager.42e [filename]

or on Windows NT for the P-code version:

$ fglpager [filename]

The fglpager command has the same functionality as pager.42e except that:
• If you do not allow the pager to use a database, the user can only scroll 10
pages backwards. To have unlimitted scrolling, the pager needs a database
name as parameter -d dbname to create temporary tables. Additionally, you
must call fgl_report_use_temptable() in the 4GL program before starting
the report. Otherwise, you can see only 10 pages backwards.
• If you execute the report with FGLGUI=0 ( i.e.: In ASCII mode ), the pager
will display all the report without stopping after each page.

To close the pager window, you have to click the STOP button. Pressing the STOP
button will not send the interruption signal but will set the int_flag variable to true.
This is for backward compatibility with older version of the pager.

Using the Four J’s Business Development Language Compiler 4-47

Miscellaneous Programs and Scripts

fglX11d
This is the command to start the graphical deamon of the X11 front-end.

fglWrt
The fglWrt tool is called by the licencef4gl program when installing or updating a
license. Normally you should use the licencef4gl tool instead of using fglWrt.

To display the license currently installed on a product, use the fglwrt -a see
command.

Sometimes, because a 4GL application was not stopped cleanly, the compiler may
think that the application is still running. This may prevent users starting a new 4GL
application if the maximum user count has been reached. To reset the number of users
currently connected without stopping the currently running 4GL application, use the
command fglwrt -u.

4-48 Four J’s Business Development Manual User Guide

Chapter

Language Extensions
5
In This Chapter . . . . . . . . . . . . . . . . . . . . 5-5
Integer Expressions as Character Subscripts . . . . . . . . . . . 5-6
Integer Expressions as Array Indexes. . . . . . . . . . . . . . 5-6
Channel Extensions . . . . . . . . . . . . . . . . . . . 5-6
Initializing Channel Extensions . . . . . . . . . . . . . . 5-7
Opening a File . . . . . . . . . . . . . . . . . . . 5-7
Opening a Pipe . . . . . . . . . . . . . . . . . . . 5-8
Setting the Default Separator . . . . . . . . . . . . . . . 5-9
Reading Data from an Opened Channel. . . . . . . . . . . . 5-9
Writing Data to a Pipe or Stream . . . . . . . . . . . . . . 5-10
Closing the Channel . . . . . . . . . . . . . . . . 5-11
Channel Error Codes . . . . . . . . . . . . . . . . . 5-11

Sharing Information Using DDE . . . . . . . . . . . . . . . 5-11

Supported Windows Applications . . . . . . . . . . . . . 5-12
Using DDE Extensions . . . . . . . . . . . . . . . . . 5-12
Transmitting Values to a Windows Program . . . . . . . . . . 5-14
Getting Values from a Windows Program . . . . . . . . . . . 5-15
Closing a DDE Connection . . . . . . . . . . . . . . . 5-15
Closing all DDE Connections . . . . . . . . . . . . . . . 5-16

Extending the DISPLAY ARRAY Statement . . . . . . . . . . . 5-17

Returning Key Code Values. . . . . . . . . . . . . . . . . 5-18
Returning Key Codes from P Code . . . . . . . . . . . . . 5-19
Returning Key Codes from C Functions . . . . . . . . . . . 5-20
Creating a Custom Character Filter . . . . . . . . . . . . . 5-21
Starting a UNIX Emulator . . . . . . . . . . . . . . . . . 5-22
Starting Windows Applications. . . . . . . . . . . . . . . . 5-22
Using Input Statement Functions . . . . . . . . . . . . . . . 5-23
Returning a Value if a Field has been Modified . . . . . . . . . 5-23
Returning the Name of a Field. . . . . . . . . . . . . . . 5-25
Returning the Value of a Field . . . . . . . . . . . . . . . 5-26
Setting the Value in a Field . . . . . . . . . . . . . . . . 5-26
Displaying a Row at a Given Line in a Screen Array. . . . . . . . 5-26

Closing the Application Window . . . . . . . . . . . . . . . 5-30

Terminating Applications . . . . . . . . . . . . . . . . . 5-31
FORM and LINE Mode with the RUN Instruction. . . . . . . . . . 5-31
SQL Syntax Support . . . . . . . . . . . . . . . . . . . 5-33
Support For Embedded SQL 7.3 Syntax . . . . . . . . . . 5-33
Support for Preparable SQL Statements . . . . . . . . . . 5-35
Year 2000 Support . . . . . . . . . . . . . . . . . . . . 5-38
Legacy Support for DBCENTURY . . . . . . . . . . . . 5-40
CENTURY Field Attribute . . . . . . . . . . . . . . . . 5-41
CENTURY Display Attribute in PROMPT Statements . . . . . . . 5-42

Screen Array Management . . . . . . . . . . . . . . . . . 5-42

Data Editing in Screen Arrays . . . . . . . . . . . . . . . 5-42
CANCEL INSERT Keywords . . . . . . . . . . . . . 5-43
CANCEL DELETE Keywords . . . . . . . . . . . . . 5-44
INSERT ROW Attribute . . . . . . . . . . . . . . . 5-45
DELETE ROW Attribute . . . . . . . . . . . . . . . 5-45
CURRENT ROW DISPLAY Attribute . . . . . . . . . . . . 5-46
COUNT Attribute . . . . . . . . . . . . . . . . . . 5-47
MAXCOUNT Attribute. . . . . . . . . . . . . . . . . 5-47
FGL_SCR_SIZE( ) Built-In Function . . . . . . . . . . . . 5-48
Report Output Configuration . . . . . . . . . . . . . . . . 5-50
START REPORT . . . . . . . . . . . . . . . . . . . 5-50

5-2 Four J’s Business Development Language User Guide

String Concatenation Operator . . . . . . . . . . . . . . . . 5-51
Equal Comparison Operator Synonym . . . . . . . . . . . . . . 5-52
Hiding the Comment Line . . . . . . . . . . . . . . . . . . 5-53
Editing Multibyte Data in 4GL Forms . . . . . . . . . . . . . . 5-53
Commenting 4GL Extensions for Compatibility . . . . . . . . . . . 5-56
Informix BOOLEAN Data Type Support . . . . . . . . . . . . . 5-57
Retrieving FGLPROFILE settings . . . . . . . . . . . . . . . 5-59
Retrieving the Current Process Identifier . . . . . . . . . . . . . 5-60

Language Extensions 5-3

5-4 Four J’s Business Development Language User Guide
In This Chapter
This chapter describes nongraphical extensions (extensions that do not affect the
database interface) that can be used to enhance Four J’s BDL applications. This
chapter includes the following sections:

• Integer expressions in character subscripts

• Integer expressions as array indexes
• Channel extensions
• Sharing information using Dynamic Data Exchange (DDE)
• Extending the DISPLAY ARRAY command
• Returning key code values
• Starting a UNIX emulator
• Starting Windows applications
• Using input statement functions
• Terminating applications
• FORM and LINE mode with the RUN instruction
• SQL syntax Support
• Year 2000 support
• Screen array management
• Report output configuration
• String concatenation operator
• Equal comparison operator synonym
• Hiding the comment line
• Editing multibyte data in 4GL forms
• Commenting 4GL extensions for compatibility
• Informix BOOLEAN data type support

Language Extensions 5-5

Integer Expressions as Character Subscripts

• Retrieving the current system process identifier

Integer Expressions as Character Subscripts

The BDL language supports full integer expressions as character subscripts.

For example:
MAIN
DEFINE s CHAR(10)
LET s=”My String”
LET s=s[1,LENGTH(s)-1]
DISPLAY s CLIPPED
END MAIN

The above example will display “My Strin”.

Integer Expressions as Array Indexes

The BDL language supports full integer expressions as array indexes.

For example:
MAIN
DEFINE a ARRAY[10,50] OF CHAR(10)
DEFINE x INTEGER
DEFINE y INTEGER
LET x=2
LET y=15
LET a[x+1,y+3] = “aaaa”
DISPLAY a[x+1,y+3]
END MAIN

Channel Extensions
Channel extensions provide access to the system, files and processes, without using
the RUN statement. With channel functions rather than the RUN statement, the appli-
cation requires fewer resources and allows communication through pipes with other
applications.

5-6 Four J’s Business Development Language User Guide

Initializing Channel Extensions

All the functions, except USE channel, are prefixed by channel:: to indicate that they
belong to the channel class.

In the section “Sharing Information Using DDE” on page 5-9, there are examples that
illustrate the use of the Dynamic Data Exchange (DDE) functions.

Initializing Channel Extensions

The following statement tells the compiler that channel extensions will be used
during the execution of the 4GL program:

Syntax USE channel

Returns None

This statement must be located before the MAIN clause in the source code. For
example:
USE channel
MAIN
…
END MAIN

Opening a File
The following function opens the file specified by filename and prepares the file
for reading or writing, as specified by oflag:

Syntax channel::open_file(handle, filename, oflag)

handle CHAR(xx) Unique identifier for the specified filename

filename CHAR(xx) Name of the file you want to open

oflag CHAR(1) r Read mode (standard input if the filename is

empty)
w Write mode (standard output if the filename is
empty)

Language Extensions 5-7

Opening a Pipe

a Append mode: writes at the end of the file (stan-

dard output if the filename is empty)
u Read from standard input and write to standard
output (filename must be empty)

Returns None

The filename is assigned to the handle that will be called for the different operations
on the opened channel. For example:
CALL channel::open_file("stream", "fglprofile", "r")

Opening a Pipe
The following function opens the pipe specified by command and prepares the pipe
for reading or writing, as specified by oflag:

Syntax channel::open_pipe(pipe_handle, command, oflag)

pipe_handle CHAR(xx) Unique identifier for the specified command

command CHAR(xx) Name of the command you want to execute

oflag CHAR(1) r Read mode

w Write mode

a Append mode: writes at the end of the file

u Read and write from command (only available for

the UNIX system)

Returns None

The command is assigned to the handle called for the different operations on the
opened channel. For example:
CALL channel::open_pipe("pipe", "ls -l", "r")

5-8 Four J’s Business Development Language User Guide

Setting the Default Separator

Setting the Default Separator

The following function allows you to change the delimiter of each opened channel
defined by its handle within a 4GL program:

Syntax CALL channel::set_delimiter(handle, delimiter)

handle CHAR(xx) Unique identifier for open channel

delimiter CHAR(1) Delimiter of field

Returns None

Because channel read/write functions are the same as those used by LOAD/UNLOAD
functions, the default separator is defined by the DBDELIMITER environment
variable. The default value is the | (pipe) character. If delimiter="" (empty
string), no delimiter is used. For example:
CALL channel::set_delimiter("pipe",",")

Reading Data from an Opened Channel

The following function reads data from the stream specified by the handle and stores
the data in a buffer.

Syntax channel::read(handle, buffer-list)

handle CHAR(xx) Unique identifier for open channel

buffer-list List of variables, if you use more than one variable, you
must enclose the list in brackets ([ ])

Returns SMALLINT TRUE if data has been read from handle; FALSE if an
error occurs

The storage buffer can be a single variable, a simple array, or a record.

Warning: Specifying a constant value as buffer-list is not detected at compile time

and will generate a core dump on UNIX computers and a general protection fault on
Windows systems.

Language Extensions 5-9

Writing Data to a Pipe or Stream

The following examples show this function. The first example shows a read function
return value in a variable buffer.
DEFINE buffer CHAR(128)
CALL channel::read("pipe_handle", buffer) RETURNING ret

The second example shows a read function returning data in a simple array:
DEFINE buffer ARRAY[1024] of CHAR(128)
DEFINE I INTEGER
LET I = 1
WHILE channel::read("pipe_handle", buffer[I])
LET I = I + 1
END WHILE

The third example shows a read function returning data in a record:

DEFINEbuffer RECORD
Buff1 CHAR(128),
Buff2 CHAR(128),
Buff3 INTEGER
END RECORD
CALL channel::read("handle", [buffer.Buff1, buffer.Buff2,
buffer.Buff3])

Writing Data to a Pipe or Stream

The following function writes data from a stored buffer to a stream:

Syntax channel::write(handle, buffer_list)

handle CHAR(xx) Unique identifier for open channel

buffer_list List of variables; if you use more than one variable,

you must enclose the list in brackets ([ ])

Returns None

The storage buffer can be a single variable, a simple array, a record, or a string
between double quotes (“). For example:
CALL channel::write("handle", "hello world")

5-10 Four J’s Business Development Language User Guide

Channel Error Codes

Closing the Channel

The following function closes the channel specified by handle:

Syntax channel::close(handle)

handle CHAR(xx) Unique identifier for open channel

Returns None

For example, assuming handle is called handle1:

CALL channel::close("handle1")

Channel Error Codes

Even though several channel functions return no error code, you can test the status of
the called function like all other 4GL functions. You can see the different error codes
returned by testing the status variables:

• 6340: Cannot open file.

• 6341: Unsupported mode for 'open file'.
• 6342: Cannot open pipe.
• 6343: Unsupported mode for 'open pipe'.
• 6344: Cannot write to unopened file or pipe.
• 6345: Channel write error.
• 6346: Cannot read from unopened file or pipe.

Sharing Information Using DDE

DDE is a form of interprocess communication that uses shared memory to exchange
data between applications. Applications can use DDE for one-time data transfers and
for ongoing exchanges in applications that send updates to one another as new data
becomes available.

With this new extension, you can invoke a Windows application and send or receive
data to or from it. To use this new functionality, the program must be executed on a
Windows PC or on a UNIX workstation but only from the Windows Client.

Language Extensions 5-11

Supported Windows Applications

Important: The tcp communication channel (socket) between the 4GL application
and the graphical server must be established with a display (OPEN WINDOW,
MENU, DISPLAY AT) before using the DDE functions.

Supported Windows Applications

Four J’s BDL supports data exchange for the following Windows applications:

• Winword 2.0x, 6.0x, 7.x

• Excel 4.0x 5.0x, 7.x
• Access 2.0 up to 97
• Netscape Navigator 3.0
Important: Please refer to your Microsoft documentation for DDE compatibility
between existing versions. As an example, DDE commands were changed between
Office 97 and Office 98.

Using DDE Extensions

The DDE 4GL process is a four-part process, as follows:

1. The 4GL application sends to the Windows Front End the DDE order using
the TCP/IP channel.
2. The Windows Front End executes the DDE order using the Tcl/Tk functions
and sends the data to the Windows application through the DDE communi-
cation process.
3. The Windows application executes the command and sends the result,
which can be data or an error code, to the Windows Front End.

5-12 Four J’s Business Development Language User Guide

Opening a DDE Connection

4. The Windows Front End sends the result to the 4GL application using the
TCP/IP channel.
Figure 5-1 illustrates this process.
Figure 5-1
DDE 4GL Process

Windows Front End Application Server

Windows Client DDE order from 4GL program 1 4GL

Tcl/Tk Program
4 DDE result from Windows Front End
TCP/IP communication
Communication2
Process DDE
order DDE
result
3

Windows Application

To start a Windows application on the client side, use the winexec function.

Opening a DDE Connection

The following function opens a DDE connection:

Syntax DDEConnect(progname, docname)

progname CHAR(128) Program name

docname CHAR(128)

Returns TRUE if the connection has been successfully opened; FALSE if

an error occurs (The error can be seen using the DDEGeterror
function.)

A DDE connection is represented by a unique identifier consisting of a program name

followed by a topic that can be a working document or system. For example:
CALL DDEConnect("EXCEL", "Document1")

Language Extensions 5-13

Executing a Program Command Using DDE

Executing a Program Command Using DDE

The following function executes a command in the specified program using the DDE
channel:

Syntax DDEExecute(progname, docname, command)

progname CHAR(128) Program name

docname CHAR(128) Working document or system

command CHAR(2048) Command executed through DDE (The syntax of the
command depends on the calling program.)

Returns TRUE if the command has been successfully executed; FALSE if the
command has encountered an error (You see the error using the DDE-
Geterror function.)

This program can be a macro or any other command available in the calling program.
For example:
LET command = "EXECUTE(\\\"macro1.xlm!Save1\\\";FALSE)"
CALL DDEExecute("EXCEL", "Document1", command ) RETURNING ret

Transmitting Values to a Windows Program

The following function sends data to the specified program and document using the
DDE channel:

Syntax CALL DDEPoke(progname, docname, cells, values)

progname CHAR(128) Program name

docname CHAR(128) Working document or system

cells CHAR(128) Working items

values CHAR(128) Data sent to the progname

Returns TRUE if the values have been successfully transmitted;

FALSE if an error occurs (The error can be seen using the function
DDEGeterror.)

5-14 Four J’s Business Development Language User Guide

Getting Values from a Windows Program

For example:
LET val="12\\t13\\t14"
CALL DDEPoke("EXECEL", "Document1", "R1C1: R2C2", val) RETURNING ret

Getting Values from a Windows Program

The following function gets values from the specified program and stores it in a
variable:

Syntax CALL DDEPeek(progname, docname, cells)

progname CHAR(128) Program name

docname CHAR(128) Working document or system

cells CHAR(128) Working items

Returns Data from the windows program;

NULL if an error occurs (The error can be seen using the
DDEGeterror function.)

Each value retrieved by the function is separated by the tabulation character. The
newline character is changed to the ASCII 13 character. For example:
CALL DDEPeek("EXCEL", "Document1", "R1C1:R2C2") RETURNING ret

Closing a DDE Connection

The following function loses the specified DDE channel represented by its unique
identifier:

Syntax CALL DDEFinish(progname, docname)

progname CHAR(128) Program name

docname CHAR(128) Working document or system

Returns TRUE if the closing action has been made;

FALSE if an error occurs (The error can be seen using the DDEGe-
terror function.)

Language Extensions 5-15

Closing all DDE Connections

For example:
CALL DDEFinish("EXCEL", "Document1") RETURNING ret

Important: All DDE functions described above must always be called with the
program name and the document name. Those names define the DDE connection.

Closing all DDE Connections

The following function closes all DDE connections, as well as the program sending
or receiving data on the DDE channels:

Syntax DDEFinishAll()

Returns TRUE if all DDE channels have been closed;

FALSE if an error occurs (The error can be seen using the
DDEGeterror function.)

For example:
CALL DDEFinshAll() RETURNING ret

5-16 Four J’s Business Development Language User Guide

Managing DDE Error Messages

Managing DDE Error Messages

The following function retrieves the last error on the DDE channel:

Syntax DDEGeterror()

Returns Error message for the current error or NULL for no error

For example:
CALL DDEGeterror() RETURNING mess

Extending the DISPLAY ARRAY Statement

The following statements extend the DISPLAY ARRAY statement:
- BEFORE ROW
statements
.
.
- BEFORE DISPLAY
statements
.
.
- AFTER ROW
statements
.
.
- AFTER DISPLAY
statements
.
.

These statements can be used exactly as in an INPUT ARRAY.

You can use also CONTINUE DISPLAY or EXIT DISPLAY.

Important: The trigger BEFORE ROW is executed before BEFORE DISPLAY, whereas
AFTER ROW is executed before AFTER DISPLAY.

Language Extensions 5-17

Returning Key Code Values

The following example shows the DISPLAY ARRAY command:

.
.
.
LET initdsp=TRUE
LET array_line=10
LET screen_line=5
DISPLAY ARRAY a TO scr.*
BEFORE DISPLAY
DISPLAY "before display"
BEFORE ROW
IF initdsp THEN
CALL fgl_dialog_setcurrline(screen_line,array_line)
END IF
LET initdsp=FALSE
AFTER ROW
LET i=arr_curr()
DISPLAY i TO a_field
ON KEY(F22)
LET i=arr_curr()
IF i == 40 THEN
EXIT DISPLAY
END IF
AFTER DISPLAY
DISPLAY "after display"
LET i=arr_curr()
IF i > 50 THEN
CONTINUE DISPLAY
END IF
END DISPLAY
.
.
.

Returning Key Code Values

You can return a key code value after pressing a keystroke. For P code, the function
is fgl_getkey. For C code, the function is uiInkey.

5-18 Four J’s Business Development Language User Guide

Returning Key Codes from P Code

Returning Key Codes from P Code

The following function waits for a keystroke and returns the key code of a pressed
key:

Syntax fgl_getkey()

Returns Value of the keystroke

Example: The following program displays a message when you press T:

MAIN
DEFINE key INTEGER

--#CALL fgl_init4js()
--#LET key = fgl_getkey ()
IF key = 116 THEN
--#CALL fgl_winmessage("fgl_winmessage", "You have pressed T", "info")
END IF
END MAIN

If you press T, you receive the message that Figure 5-2 shows.
Figure 5-2
fgl_winmessage
Window

This function can be used in association with the fgl_keyval() function of 4GL. The
following table shows the values returned by the fgl_getkey function.

Value Returned Meaning

0 through 255 A single character from the ISO8859-1 character set.

This does not apply if you are using a GLS locale with another
character set.
For more information, see the INFORMIX-4GL Reference.

3000 through 3063 Function keys F1 through F64.

2000 Up Arrow
(1 of 2)

Language Extensions 5-19

Returning Key Codes from C Functions

Value Returned Meaning

2001 Down Arrow

2002 Left Arrow

2003 Right Arrow

2004 Backup key

2005 Next Screen

2006 Previous Screen

2008 Help

2009 Insert Character

2010 Delete Character

2011 Interrupt

2012 Home

2013 End

2014 Insert Line

2015 Delete Line

2016 Accept

2018 Autonext (returned whenever an auto-next field is exited, regardless

of which key was actually pressed.)

4003 DEL
(2 of 2)

Returning Key Codes from C Functions

In C functions, the equivalent of the function fgl_getkey() used to wait for
a keystroke is uiInkey(), as follows:

Syntax uiInkey()

Returns Value of the keystroke

5-20 Four J’s Business Development Language User Guide

Creating a Custom Character Filter

Creating a Custom Character Filter

You can create your own character filter that converts the key codes sent by the
program to the interface (and vice versa). First, you must compile the C program
$FGLDIR/src/mkchartab.c. This program allows you to convert an input file that
contains the new key code mapping to an output file that Four J’s BDL can use.

An example of a mapping file is $FGLDIR/src/ansinogr.map. Once compiled with

the mkchartab tool, this file is the same as the current $FGLDIR/etc/iso/ansinogr.ct
file. You can then use the fgl.chartable.file entry in the configuration file.

The filter source files contain two sections, an output section and an input section.
The output section contains the conversion table for the characters going to the output
device (the screen). The input section contains the conversion table for the characters
coming from the input device (the keyboard).

The following example is for the file ansinogr.map:

#########################################################
# Character conversion ANSI ==> VT100
# Input section, output section
# Syntax :
# [input|output]
# x y
# x is replaced by y
# x and y possible values are : 'x',0xDDDD , DDDDD ( D =
# digit )
# List of mapped characters :
# A", E", I", O", U", a", e", i", o", u",
# ss,
# A`, E`, I`, O`, U`, a`, e`, i`, o`, u`,
# A', E', I', O', U', a', e', i', o', u'
#########################################################
output
0x8e 0xc4
0x80 0xc7
0x90 0xc9
" "
" "
" "
input
0xc4 0x8e
0xc7 0x80
0xc9 0x90
" "
" "
" "

Language Extensions 5-21

Starting a UNIX Emulator

Starting a UNIX Emulator

This function allows a RUN of a program needing a UNIX terminal emulator on the
Windows client, even if the running F4GL program has been started without a visible
terminal.

Syntax fgl_system (command)

In this syntax, command is a string or variable that contains the commands to be run.
The UNIX terminal will be raised and activated and then lowered later, when the
parent program finishes.

Running this function correctly requires the termcap entries hp (for raising the
terminal) and rp (for lowering the terminal). For the Windows front end terminal
emulation, the entries should have the values:
:hp=\E[0y:rp=\E[1y:\

Starting Windows Applications

The following functions start a Windows program on the computer that runs the
Windows Client.

Syntax WinExec (progname) Starts a program on the Windows Client

without waiting for its end to resume execu-
tion of the 4GL program

WinExecWait Starts a program on the Windows Client

(progname) and waits for its end to resume execution

where

progname CHAR(256) Program name with or without its absolute

path

Example:
LET var = WinExec("C:\\\\EXCEL\\\\EXCEL.EXE")

This line starts excel.exe on the Windows PC running the front end.

5-22 Four J’s Business Development Language User Guide

Using Input Statement Functions

Those functions return TRUE if the application is successfully started. If FALSE is

returned, you can see the error using the function DDEGeterror.

Four back slashes are needed as escape characters to transmit one to the client
computer.

Important: The tcp communication channel (socket) between the 4GL application
and the graphical server must be established with a display (OPEN WINDOW,
MENU, DISPLAY AT) before using the WinExec function.

Using Input Statement Functions

The following set of functions must be executed inside dialog functions, such as
INPUT, INPUT ARRAY, DISPLAY ARRAY, and PROMPT statements. Using these
functions outside of a dialog function might create errors at compile time or at
runtime.

Returning a Value if a Field has been Modified

The following function is called by AFTER { FIELD | INPUT | CONSTRUCT } and
returns a value that indicates whether or not the last field has been modified:

Syntax fgl_buffertouched()

Returns TRUE if the last field has been modified

Language Extensions 5-23

Returning a Value if a Field has been Modified

The following source code tests if an update must be made after an input only on the
last field. If something has changed during the input, a dialog box will be displayed
that asks you if you want to accept the input. If not, a message appears informing you
that nothing has to be done.
MAIN
DEFINE answer, CHAR(100),
inst RECORD
c1, c2, c3, c4, c5, c6, c7, c8, c9, c10 CHAR(100)
END RECORD
--#CALL fgl_init4js()
OPEN WINDOW w1 AT 1,1 WITH FORM "demo"
LET answer = "no"

WHILE answer != "yes"

INPUT BY NAME inst.*
--# AFTER FIELD c10
--# IF fgl_buffertouched() THEN
--# LET answer = fgl_winquestion("Notice", "Do you want to accept
this
--# row","yes", "yes|no", "info",0)
--# ELSE
--# CALL fgl_winmessage("Notice", "Nothing to be done", "info")
--# LET answer = "no"
--# END IF
--# END INPUT
END WHILE
CLOSE WINDOW w1
END MAIN

The first screen displays the form with ***** as the default value, as Figure 5-3
illustrates.
Figure 5-3
Default Value
Screen

5-24 Four J’s Business Development Language User Guide

Returning the Name of a Field

If you exit the input without updating the row, the dialog box that Figure 5-4 shows
appears and informs you that no changes to the row have been made.
Figure 5-4
Exiting Without
Update Screen

If something has changed during the input, the dialog box that Figure 5-5 shows
appears.
Figure 5-5
Prompt for
Accepting
Changes

Returning the Name of a Field

The following function returns the name of the currently prompted field:

Syntax fgl_dialog_getfieldname()

Returns Name of current field

Language Extensions 5-25

Returning the Value of a Field

Returning the Value of a Field

The following function returns the value of the currently prompted field:

Syntax fgl_dialog_getbuffer()

Returns Value of current field

Example See fgl_dialog_setbuffer() example below

Setting the Value in a Field

The following function sets a value in the currently prompted field:

Syntax fgl_dialog_setbuffer(var)

var Value or variable containing the value to be set in the current field

Returns None

Displaying a Row at a Given Line in a Screen Array

The following function displays a row of the program array to be set at a given line
of the screen array:

Syntax fgl_dialog_setcurrline (scrl, progl)

scrl Line of the screen array becoming current

progl Line of the program array becoming current

Returns None

5-26 Four J’s Business Development Language User Guide

Displaying a Row at a Given Line in a Screen Array

The following example creates a display array with two on key options. When you
press F4, the 100th row of the program record is displayed at the fifth line of the
screen array, and when you press F5, the 400th row of the program record is displayed
at the first line of the screen array.
MAIN
DEFINE a ARRAY[500] OF RECORD
c1 CHAR(10),
c2 CHAR(12),
c3 char(10)
END RECORD
DEFINE i INTEGER

--#CALL fgl_init4js()
FOR i = 1 TO 500
LET a[i].c1 = i CLIPPED
LET a[i].c2 = "555-666-" CLIPPED, a[i].c1
LET a[i].c3 = "Washington"
END FOR
OPEN WINDOW w1 AT 1,1 WITH FORM "demo"
CALL SET_COUNT(i)
DISPLAY ARRAY a TO scr.*
--#ON KEY(f4)
--#CALL fgl_dialog_setcurrline(5,100)
--#ON KEY(f5)
--#CALL fgl_dialog_setcurrline(1, 400)
END DISPLAY
CLOSE WINDOW w1
END MAIN

Language Extensions 5-27

Displaying a Row at a Given Line in a Screen Array

Compile this program with the following form:

DATABASE formonly
SCREEN
{
CODE Phone Number City
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
[f001 ] [f002 ] [f003 ]
}
ATTRIBUTES
f001 = formonly.c1, UPSHIFT;
f002 = formonly.c2, UPSHIFT;
f003 = formonly.c3;
END
INSTRUCTIONS
DELIMITERS " "
SCREEN RECORD scr[7] (formonly.c1,
formonly.c2,
formonly.c3);
--#keys
--#f4 = "100 th"
--#f5 = "400 th"
END

5-28 Four J’s Business Development Language User Guide

Displaying a Row at a Given Line in a Screen Array

After executing the program, an array appears with four buttons on the right side of
the dialog box, as Figure 5-6 shows. Accept and Interrupt are created automatically
by the program due to the fglprofile configuration.
Figure 5-6
setcrline Dialog
Box

Language Extensions 5-29

Closing the Application Window

If you press F4 or click the 100th button, the screen array that Figure 5-7 shows is
displayed with the fifth row being current in the screen record displaying the 100th
row from the program array.
Figure 5-7
setcrline Dialog
Box

Now press F5 or click the 400th button. The form is displayed with the first row being
current and containing the 400th row of the program array.

Closing the Application Window

The following option allows to execute a 4GL function when the application window
is closed by a user action, for example, ALT-F4 on Windows clients:

Syntax OPTIONS ON CLOSE APPLICATION {STOP|CONTINUE|

CALL func}

Returns None

If this option is not used, the application displays a warning message when then user
is trying to close the application window.

5-30 Four J’s Business Development Language User Guide

Terminating Applications

Terminating Applications
This option defines the function that must be called when the application receives the
SIGTERM signal.

Syntax OPTIONS ON TERMINATE SIGNAL CALL func

Returns None

If this statement is not called, the program is stopped with the exit value of SIGTERM
(15).

In Windows, the function will be called in the following cases:

• the console window that the 4GL program was started from is closed
• the current user session is terminated (i.e. the user logs off)
• the system is shut down
Tip: You can stop the program in a clean manner using ROLLBACK WORK. However,
this does not have any user interaction.

FORM and LINE Mode with the RUN Instruction

The RUN instruction can execute programs in FORM or LINE mode.

Syntax:
RUN command [IN (FORM|LINE) MODE] [RETURNING variable]
[WITHOUT WAITING]

Note: This syntax is compatible with Informix-4gl version 6.0 or higher.

Standard behavior of a 4gl program

4gl programs operate by default in LINE mode when no interactive instruction, such
as DISPLAY AT, OPEN WINDOW or DISPLAY FORM, is being executed.

When using interactive instructions, the FORM mode is enabled.

Language Extensions 5-31

Using character terminals

The terminal mode may be controlled with the FORM/LINE MODE option of the
RUN command when running programs that may or may not be interactive.

Using character terminals

In LINE MODE, the terminal is in the same state (stty options) as when the program
began. This usually means that the terminal input is in cooked mode (rather than raw
mode).

In FORM MODE, the terminal is in raw mode, so each character is available to the
program as it is read, rather than becoming available when the newline character is
typed (cooked mode).

After a RUN with FORM MODE option, the program remains in FORM MODE if
it is currently in FORM MODE, but it does not enter FORM MODE if it is currently
in LINE MODE.

After a RUN with specified LINE MODE option, the program remains in LINE
MODE if it is currently in LINE MODE, and it switches to LINE MODE if it is
currently in FORM MODE.

Using graphical clients

In graphical mode, the terminal (if it exists) is always in the same state as when the
program began.

After a RUN with specified FORM MODE option, the program suppresses the
raising of the window which contains the current application. Normally, this raise is
done when user interaction is requested.

After a RUN with specified LINE MODE option, the program raises the window
which contains the current application.

Defining the default MODE with OPTIONS

The OPTIONS instruction can define the default mode for all RUN instructions.

5-32 Four J’s Business Development Language User Guide

SQL Syntax Support

Syntax:
OPTIONS RUN IN ( FORM | LINE ) MODE

Complete example:
MAIN
DISPLAY "something" AT 1,1 -- switch to form mode
RUN "foo" -- switch to line mode: the default
is LINE
DISPLAY "something" AT 1,1 -- switch to form mode
RUN "foo" IN FORM MODE -- keep form mode
RUN "foo" IN LINE MODE -- switch to line mode
OPTIONS RUN IN FORM MODE -- set the default mode to FORM
DISPLAY "something" AT 1,1 -- switch to form mode
RUN "foo" -- keep form mode: the default is
FORM
RUN "foo" IN FORM MODE -- keep form mode
RUN "foo" IN LINE MODE -- switch to line mode
OPTIONS RUN IN LINE MODE -- set the default mode to LINE
(initial value)
END MAIN

SQL Syntax Support

Like all earlier releases since 4GL 4.10, this release supports most of the statement
set of Version 4.1 of the Informix dialect of SQL language. These SQL statements can
be directly embedded within 4GL source files. Statements and syntax enhancements
added later than Version 4.10 of SQL must be prepared, if they are preparable.

Support For Embedded SQL 7.3 Syntax

4GL 7.30 supports all the directly embedded SQL statements that earlier releases of
4GL could embed, but also adds direct support for the following additional SQL
statements:

• CONNECT
• CREATE PROCEDURE FROM

Language Extensions 5-33

SQL Syntax Support

• DISCONNECT
• EXECUTE IMMEDIATE
• SET CONNECTION

5-34 Four J’s Business Development Language User Guide

SQL Syntax Support

4GL 7.30 also supports the following additional SQL syntax features:

• EXECUTE
The EXECUTE statement now supports the INTO and USING clauses in both
orders:
{ { [INTO varlist1] [USING varlist2] } |
{ [USING varlist1] [INTO varlist2] } }
• FOREACH
The FOREACH statement now supports the WITH REOPTIMIZATION
clause:
{ [USING varlist1] WITH REOPTIMIZATION [INTO varlist2] }
• OPEN
The OPEN statement now supports the WITH REOPTIMIZATION clause:
{ [USING varlist] WITH REOPTIMIZATION }

The non-keyword terms in these SQL statements can be specified as quoted strings or
as character variables.

These SQL statements require an Informix database that recognizes them. When Four
J’s BDL accesses an Informix database earlier than Version 7.x, for example, the
WITH REOPTIMIZATION clause has no effect.

Support for Preparable SQL Statements

Earlier releases of 4GL supported post-4.10 SQL syntax by the PREPARE feature, for
SQL statements that can be prepared.

Continued Support Through PREPARE

4GL 7.30 continues to support the preparable SQL syntax of Informix 7.30 database
servers. See the Informix Guide to SQL: Syntax description of PREPARE for a list of
the SQL statements that cannot be prepared.

Language Extensions 5-35

SQL Syntax Support

New SQL Statement Blocks

The same preparable statements that Section 2.1 describes are also supported in 4GL
7.30 by a new mechanism, SQL statement blocks, whose syntax resembles that of
embedded SQL statements in ESQL/C:
SQL statement END SQL

Only a single preparable SQL statement can appear in each SQL block. If you delimit
a preparable SQL statement by the keyword SQL before the SQL statement, and by the
keywords END SQL after the SQL statement, then 4GL 7.30 prepares, executes, and
frees the specified SQL statement when its SQL block is encountered, as in this
example:
SQL
BEGIN WORK
END SQL

Any 4GL variables that appear within an SQL block must be prefixed by the $ symbol.
One or more whitespace characters, such as blank spaces, can appear between $ and
the name of the host variable.
SQL
UPDATE SomeTable
SET (Col2, Col3, ... ColN) = ($rec.col1 THRU $rec.colN)
WHERE CURRENT OF somecursor
END SQL

In the declaration of a database cursor, the following syntax that includes an SQL
statement block within a DECLARE statement is valid:
DECLARE curs CURSOR
SQL
... -- define the SELECT, UPDATE, or INSERT cursor
END SQL

An SQL block, however, cannot appear within a PREPARE statement.

5-36 Four J’s Business Development Language User Guide

SQL Syntax Support

SQL blocks of 4GL 7.30 (and Four J’s BDL 3.0) support both singleton EXECUTE
PROCEDURE statements that return values and singleton SELECT statements that
return values, as in the following examples:
SQL
EXECUTE PROCEDURE someproc(1, $invar) INTO $var1, $var2
END SQL

SQL
SELECT Col1, Col2 INTO $var1, $var2
FROM SomeTable WHERE PKey = $var3
END SQL

The EXECUTE IMMEDIATE statement cannot appear within an SQL block.

Question-mark place-holders (?) in SQL blocks can appear in strings that are
prepared, but not in other contexts. Thus, the following code generates a syntax error:
DECLARE cname CURSOR FOR
SQL
SELECT * FROM SomeWhere
WHERE SomeColumn BETWEEN ? AND ? -- Invalid!!!
END SQL

Trailing semicolon (;) symbols are valid after the SQL statement, but have no effect.
Semicolons that separate two statements within the SQL block cause a syntax
violation error message to be issued by the compiler. This causes the compilation to
fail.

Optimizer directives and comments within delimited SQL statement blocks are
passed to the database server, if you use the standard notation for these features in
Version 7.30 and later Informix database servers. Such directives can immediately
follow the DELETE, SELECT, or UPDATE keywords in SQL data manipulation state-
ments. The plus ( + ) sign must be the first character following the comment indicator
that begins an optimizer directive. The sharp ( # ) symbol is not a valid comment
indicator in this context, but braces ( { } ) or double-hyphen ( -- ) comment indicators
are valid within an SQL block.

For more information, see the Informix Guide to SQL: Syntax.

Language Extensions 5-37

Year 2000 Support

Year 2000 Support

Some users (and some applications) abbreviate year values during data entry, so that,
for example, September 9, 1999 might be entered as 9/9/99 (or with some other order
of time units or time-unit separator symbols). Most earlier releases of 4GL expanded
abbreviated year values by prefixing any 2-digit year with the two leading digits of
the current year from the system clock.

5-38 Four J’s Business Development Language User Guide

Year 2000 Support

Examples of statements of SQL and other 4GL statements and operators that can
specify abbreviated year values include the following:
SELECT * FROM customer_name WHERE call_dtime
BETWEEN (98-01 01) YEAR TO DAY AND DATETIME (04-12 31) YEAR TO DAY

UPDATE customer SET (city, reg_date)=("Palo Alto","12/01/04")

WHERE customer_num = 103

INSERT INTO newtable SELECT dates FROM oldtable WHERE date1 "01/05/24"

DELETE FROM orders where order_date IN ("01/01/98", "12/31/04")

PREPARE up_sel FROM 'SELECT * FROM customer WHERE cust_date < "01/01/00"'

DEFINE cust_date DATE

LET cust_date = "02/29/00"
PROMPT for cust_date

DEFINE cust_date DATETIME YEAR TO DAY

LET cust_date = "00-02-29"
PROMPT for cust_time

DATE()
DEFINE d DATE
LET d = DATE ("02/29/00") ---- default DATE format
LET d = DATE ("00-29-02") ---- format Y2MMDD-

EXTEND()
DEFINE d1 DATETIME YEAR TO MINUTE
LET d1 = EXTEND("02/28/00" YEAR TO MINUTE)

UNITS
DEFINE d1 INTERVAL DAY TO DAY
LET d1 = (DATE("03/01/00") - DATE("02/28/00")) UNITS DAY

WEEKDAY()
DEFINE d1 INT
LET d1 = WEEKDAY("02/28/00")

YEAR()
DEFINE d1 INT
LET d1 = YEAR ("02/28/00")

The CONSTRUCT, INPUT, and INPUT ARRAY statements can assign to variables the
values that the user enters into the fields of the screen form.

Language Extensions 5-39

Year 2000 Support

Legacy Support for DBCENTURY

Four J’s BDL supports the DBCENTURY environment variable, which can be set to
any of four values, each of which specifies a different rule for expanding 2-digit
years. (If the user enters a single-digit year, 4GL prefixes this digit with a leading
zero, and then applies the current expansion rule to the 2-digit result.) This support is
continued in version 3.

You can set DBCENTURY as you would any other environment variable. The valid
settings (and the expansion rule that each specifies) are listed here:

Setting Expansion Algorithm

R Prefix the entered value with the first two digits of the current year (from the
system clock-calendar at runtime).

C Prefix the entered value with the first two digits of the past, current, or future
year that gives a date that is closest to the current date (from the system clock-
calendar).

P Prefix the entered value with the first two digits of the past (or current) year
that gives the most recent date in the past.

F Prefix the entered value with the first two digits of a future (or current) year
that gives the earliest date in the future.

For example, on UNIX systems that use the C shell, the specification
setenv DBCENTURY=C

instructs 4GL to expand 2-digit years to the closest date.

DBCENTURY is case-sensitive. If DBCENTURY is not set, or set to an invalid value

(such as any lowercase letter), then the default is R, which emulates the legacy
behavior of most previous 4GL releases.

Unless you override DBCENTURY (as described in the next section), 4GL applies the
DBCENTURY value that was in effect when program execution began to all year
values (in DATE or DATETIME fields only) that have fewer than 3 digits; as with
other environment variables, changing the DBCENTURY setting after program
execution commences has no effect on any currently executing 4GL program. The
results of using DBCENTURY are sensitive to the time of program execution and to
the accuracy of the system clock-calendar.

5-40 Four J’s Business Development Language User Guide

CENTURY Field Attribute

DBCENTURY has no effect on fields that are not of the DATE or DATETIME data
types, nor on DATETIME values that do not include YEAR as its first time unit, nor
on year values that are not abbreviated. It can also affect data-type conversion of
properly-formatted character strings that you assign to DATE or DATETIME
variables.

To avoid expansion of years in the remote past that have only one or two digits, you
must pad such values on the left with leading zeros, so that they have at least 3 digits.

CENTURY Field Attribute

The DBCENTURY environment variable provides a global default rule for expanding
2-digit years. CENTURY provides the same functionality as DBCENTURY but at the
field level of granularity. Unlike DBCENTURY, which provides a global expansion
algorithm, different DATE or DATETIME fields can have different CENTURY
settings. It supports the same R, C, P, and F settings as DBCENTURY, with the same
semantics. It has this syntax:
CENTURY = { "F" | "C" | "P" | "R" }

Unlike DBCENTURY, the CENTURY field attribute is not case-sensitive. For

example,
field-tag = ship_date, CENTURY = "C"

and
field-tag = ship_date, CENTURY = "c"

are equivalent. However, quotes are required around the setting.

If a DATE or DATETIME field has no CENTURY attribute, the DBCENTURY setting

(or the R default, if DBCENTURY is not set) determines the expansion rule.

If CENTURY and DBCENTURY have different settings, then CENTURY takes prece-
dence in the DATE and DATETIME fields that have this attribute.

Just as with DBCENTURY, the results of using CENTURY are sensitive to the time of
program execution and the accuracy of the system clock-calendar.

CENTURY has no effect on fields that are not DATE or DATETIME data types, nor on
DATETIME values that do not include YEAR as the first time unit, nor on unabbre-
viated year values. CENTURY can also affect conversion of properly-formatted
character strings to DATE or DATETIME variables.

Language Extensions 5-41

CENTURY Display Attribute in PROMPT Statements

CENTURY is not needed for fields that display data from the database (as distinct
from fields in which users enter data), because DATE columns of the database (and
DATETIME columns that include the YEAR time unit) store only 4-digit years, even
if a display field of the 4GL application is designed to show only trailing digits of
YEAR values from the database.

CENTURY Display Attribute in PROMPT Statements

The PROMPT statement of 4GL can request that the user enter a value. If the response
value will be stored in a DATE or DATETIME variable, you can include CENTURY in
the ATTRIBUTE clause that follows the FOR keyword, using the same semantics as
in a form specification. The following PROMPT statement sets the expansion rule to
the nearest date in the future:
DEFINE pasture DATE
PROMPT "When will you retire?" ATTRIBUTE (BLUE, REVERSE) FOR pasture
ATTRIBUTE (GREEN, CENTURY = "F") ON KEY (F1) EXIT PROGRAM
END PROMPT

The value that follows the = symbol must appear within quotation marks, like the
setting of the CENTURY field attribute.

Important: Four J’s BDL requires Client SDK 2.30 to support the CENTURY
attribute.This attribute does not run on NT with GLS functionality.

Screen Array Management

Four J’s BDL supports several features that enhance the syntax of the INPUT ARRAY
statement (and in some cases, DISPLAY ARRAY) to support program control over
screen arrays.

Data Editing in Screen Arrays

The programmer can prevent the user from performing Insert or Delete operations
during the INPUT ARRAY statement. Such restrictions can be global to the entire
screen array or can apply only to specific screen records.

5-42 Four J’s Business Development Language User Guide

Data Editing in Screen Arrays

CANCEL INSERT Keywords

Insert operations by the user can be cancelled programmatically for individual screen
records of the current 4GL form by including the CANCEL INSERT keywords within
the BEFORE INSERT control block. The cancelled Insert operation has no effect on
the active set of rows that INPUT ARRAY is processing.

The syntax for the BEFORE INSERT control block of INPUT ARRAY statements is:
INPUT ARRAY ...
BEFORE INSERT statement... { CANCEL INSERT }

Here statement is any statement of 4GL that is valid within a BEFORE INSERT control
block of INPUT ARRAY.

If CANCEL INSERT is specified, the user is prevented from entering rows by using
the Insert key. This feature also prevents the user from entering rows by moving the
screen cursor past the last initialized row by using an ARROW key, TAB key, RETURN
key, or (in Four J’s BDL) the ENTER key.

Here is a code example:

INPUT ARRAY ...
BEFORE INSERT
IF ARR_CURR() == 3
THEN
CANCEL INSERT
END IF
END INPUT

This example disables the Insert key for the third row only.

In contexts like this, two cases arise:

Case 1: The form is already populated with data.

Suppose that it contains five rows filled with data. If the cursor comes to the
third (populated) row and F1 is pressed, a new row is not inserted, because
CANCEL INSERT prevents any Insert operation for this row.Case 2: Only
some of the rows are filled with data.
Suppose that only two of a possible five rows contain data. In this case, the
user cannot move to the third row using the ARROW, TAB or RETURN key,
because CANCEL INSERT prevents any Insert operation for this row.
For more information about CANCEL INSERT, see “CANCEL DELETE
Keywords” on page 5-38.

Language Extensions 5-43

Data Editing in Screen Arrays

CANCEL DELETE Keywords

Delete operations by the user can also be cancelled programmatically for individual
screen records of the current 4GL form by including the CANCEL DELETE keywords
within the BEFORE DELETE control block. The cancelled Delete operation has no
effect on the active set of rows that INPUT ARRAY is processing.

The syntax for the BEFORE DELETE control block of INPUT ARRAY statements is:
INPUT ARRAY ...
BEFORE DELETE statement... { CANCEL DELETE }

Here statement is any statement of 4GL that is valid within a BEFORE DELETE
control block of INPUT ARRAY.

If CANCEL INSERT or CANCEL DELETE is executed, the current BEFORE INSERT or

BEFORE DELETE control block is terminated, and control of program execution
passes to the next statement that follows the terminated control block.

As an example, the programmer might want to implement a system where the user is
allowed to delete all but one of the rows, but once a row is deleted, a replacement row
cannot be inserted in its place. The following code implements this design:
DEFINE n_rows INTEGER
DEFINE arrayname ARRAY[100] OF RECORD
...

INPUT ARRAY arrayname WITHOUT DEFAULTS FROM s_array.*

ATTRIBUTES(COUNT = n_rows, MAXCOUNT = n_rows,
INSERT ROW = FALSE, DELETE ROW = TRUE)

BEFORE INSERT
CANCEL INSERT

BEFORE DELETE
LET n_rows = n_rows - 1
IF n_rows <= 0 THEN
CANCEL DELETE
END IF

END INPUT

5-44 Four J’s Business Development Language User Guide

Data Editing in Screen Arrays

INSERT ROW Attribute

Four J’s BDL supports another syntax feature that provides a means by which the
programmer can enable or disable Insert operations for the entire form during INPUT
ARRAY statements. The INSERT ROW attribute can be set to TRUE or FALSE in the
ATTRIBUTE clause that follows the INPUT ARRAY binding clause.

The attribute has this syntax:

INSERT ROW [ = { TRUE | FALSE } ]

When INSERT ROW = FALSE is specified, the user cannot perform any Insert actions
within the INPUT ARRAY statement.

For additional information about the INSERT ROW attribute in INPUT ARRAY state-
ments, see “DELETE ROW Attribute” on page 5-39.

DELETE ROW Attribute

Four J’s BDL also supports a syntax feature that provides a means by which the
programmer can enable or disable Delete operations for the entire form during INPUT
ARRAY statements. The DELETE ROW attribute can be set to TRUE or FALSE in the
ATTRIBUTE clause that follows the INPUT ARRAY binding clause.

The attribute has this syntax:

DELETE ROW [ = { TRUE | FALSE } ]

When DELETE ROW = FALSE is specified, the user cannot perform any DELETE
actions within the INPUT ARRAY statement.

When INSERT ROW = TRUE or DELETE ROW = TRUE is specified, then the user is
not prevented from performing the action for which TRUE is specified.

The default in both cases is TRUE, which corresponds to the legacy behavior of
previous 4GL releases.

In Four J’s BDL 3.0, these attributes have an extended syntax:

INSERT ROW [ = { TRUE | FALSE | var } ]
DELETE ROW [ = { TRUE | FALSE | var } ]

Here var is a variable that contain a Boolean value. If the value of var is zero or
FALSE or NULL, then the value of the attribute is FALSE. For other values of var (or
by default, if no value is specified) the value of the attribute is TRUE.

Language Extensions 5-45

CURRENT ROW DISPLAY Attribute

The following example disables Insert and Delete operations on rows of the screen
array:
INPUT ARRAY arrayname WITHOUT DEFAULTS FROM s_array.*
ATTRIBUTE(INSERT ROW = FALSE, DELETE ROW = FALSE)

CURRENT ROW DISPLAY Attribute

This attribute enables the 4GL programmer to highlight the current row of a screen
array. Four J’s BDL always highlights the current row in GUI mode, so this attribute
is primarily useful in character-based deployment. This attribute is ignored with a
graphical interface.

For both DISPLAY ARRAY and INPUT ARRAY, the ATTRIBUTE clause can include
the following syntax:
CURRENT ROW DISPLAY = "string"

Here string is a comma-separated list of screen attributes. The string can include zero
or more intensity attributes from among the following:

• REVERSE
• UNDERLINE
• BOLD
• BLINK

The string can also include one or none of the color attributes from among the
following:

• BLACK
• BLUE
• CYAN
• GREEN
• MAGENTA
• RED
• WHITE
• YELLOW

These attributes are applied to the current row of the screen array. The content of
string is not case-sensitive.

5-46 Four J’s Business Development Language User Guide

COUNT Attribute

An error is issued if string is an empty string:

CURRENT ROW DISPLAY = "" --Error!

The following statement sets the CURRENT ROW DISPLAY attribute:

INPUT ARRAY arrayname WITHOUT DEFAULTS FROM s_array.*
ATTRIBUTE (BOLD, CURRENT ROW DISPLAY = "RED, REVERSE", UNDERLINE)

The rows other than the current row in this array are displayed in bold and underlined,
but the current row is displayed in red and in reverse video. If there is only one row
in the screen array, then the current row is the only one that is displayed.

COUNT Attribute
The COUNT attribute can specify the number of records within a program array that
contain data. It can appear within the ATTRIBUTE clause of the INPUT ARRAY
statement.

COUNT has the following syntax:

COUNT = { n | var }

where n is a literal integer, and var is an INTEGER or SMALLINT variable. The

specification:
COUNT = 5

is equivalent to the 4GL statement:

CALL SET_COUNT(5)

Both of these specifications declare the initial/actual number of rows in the program
array to the INPUT/DISPLAY ARRAY instruction.

MAXCOUNT Attribute
The MAXCOUNT attribute can specify the dynamic size of a screen array. This can
be less than the declared size that the INSTRUCTIONS section of the .per file specifies
for the screen array. MAXCOUNT is valid only within the ATTRIBUTE clause of the
INPUT ARRAY statement.

MAXCOUNT has this syntax:

MAXCOUNT = { n | var }

Language Extensions 5-47

FGL_SCR_SIZE( ) Built-In Function

where n is a literal integer, and var is an INTEGER or SMALLINT variable. The

following example shows an INPUT ARRAY statement that specifies both the
MAXCOUNT and COUNT attribute:

INPUT ARRAY prog_array WITHOUT DEFAULTS

FROM scr_array.* ATTRIBUTE( MAXCOUNT = x, COUNT = y )

Here x and y are literal integers or integer variables. In this example, y is the number
of records that contain data within the program array. The MAXCOUNT value of x
determines the dynamic size of the screen array that displays the program array.

If MAXCOUNT is specified as less than one or greater than the declared program
array size, then the original program array size is used as the MAXCOUNT value.

Both COUNT and MAXCOUNT can be specified in the same ATTRIBUTE clause:
CALL SET_COUNT(5)
INPUT ARRAY prog_array WITHOUT DEFAULTS
FROM scr_array.* ATTRIBUTE(MAXCOUNT = 10, COUNT = 6)

In this case, the COUNT attribute overrides the SET_COUNT value. The number of
rows displayed will be 6.

FGL_SCR_SIZE( ) Built-In Function

This function accepts as its argument the name of a screen array and returns an
integer that corresponds to the number of screen records in that screen array.

It has this calling syntax:

FGL_SCR_SIZE ( { "array" | var } )

where array is the name of the screen array, as declared in the INSTRUCTIONS
section of the form specification. This can appear in the function call as an identifier
enclosed between quotation marks, or as a character variable containing the name of
the screen array.

5-48 Four J’s Business Development Language User Guide

FGL_SCR_SIZE( ) Built-In Function

The following form-specification file (called file.per) declares a screen array that the
subsequent 4GL code example references:
DATABASE FORMONLY

SCREEN
{
[f1 ] [f2 ]
[f1 ] [f2 ]
[f1 ] [f2 ]
[f3 ] [f4 ]
[f3 ] [f4 ]
[f5 ]
}

ATTRIBUTES
f1 = FORMONLY.a ;
f2 = FORMONLY.b ;
f3 = FORMONLY.c ;
f4 = FORMONLY.d ;
f5 = FORMONLY.e ;

INSTRUCTIONS
DELIMITERS ""
SCREEN RECORD s_rec1[3] (a,b)
SCREEN RECORD s_rec2 (c,d)

The following 4GL program invokes the FGL_SCR_SIZE( ) function:

MAIN

DEFINE n1,n2 INT

DEFINE ch CHAR(10)

OPEN WINDOW w1 AT 2,3 WITH FORM "file" ATTRIBUTE (BORDER)

CALL fgl_scr_size("s_rec1") RETURNING n1
LET n1 = fgl_scr_size("s_rec1") -- Can also be called
-- in a LET statement
DISPLAY "n1 = ", n1

LET ch = "s_rec2"
CALL fgl_scr_size(ch) RETURNING n2
LET n2 = fgl_scr_size(ch) -- Can also be called
-- in a LET statement
DISPLAY "n2 = ", n2
CLOSE WINDOW w1
END MAIN

Language Extensions 5-49

Report Output Configuration

This example produces the following output:

n1 = 3
n2 = 2

The proper value is returned, even though the array dimension is not specified.

An error is returned if no form is open, or if the specified screen array is not in the
current open form.

Report Output Configuration

START REPORT
The START REPORT statement, enables you to redefine all the values of the
OUTPUT section of a report so that the destination and dimensions of output from
the report can be specified at runtime.

If you do not use START REPORT to specify these parameters, then the OUTPUT
section values (or default values, if the OUTPUT section omits any specification)
remain in effect, as in previous releases. The syntax of START REPORT is:
START REPORT report
[TO {
SCREEN |
PRINTER |
FILE {"file"|var} |
{"file"|var} |
PIPE [ IN {FORM|LINE} MODE] {"program"|var} |
OUTPUT {"out"|var} [DESTINATION {"trg"|var}]
}
]
[WITH {
TOP OF PAGE = "string" |
PAGE LENGTH = n |
TOP MARGIN = n |
BOTTOM MARGIN = n |
LEFT MARGIN = n |
RIGHT MARGIN = n |
[,...]
}
]

5-50 Four J’s Business Development Language User Guide

String Concatenation Operator

Here n is an integer expression, and each instance of var is a 4GL program variable
whose logical content is the string at the left of the preceding pipe (|) symbol.

Here out must be one of the following:

"SCREEN", "PRINTER", "FILE", "PIPE"

These out keywords are not case-sensitive.

Here trg is the name of a file or program to receive the report output from a pipe. If
out has the value SCREEN or PRINTER, then the DESTINATION clause is not needed
(and is ignored, if specified).

The WITH clause supports the TOP OF PAGE = "string" option, which substitutes a
page-eject string for repeated Linefeeds to complete the current page of report output
and begin the next page. See your printer documentation for the appropriate string
value. Only the first character in the string is passed to the printer. (This feature can
reduce the time required to print long reports.)

Example:
START REPORT repname TO OUTPUT string1 DESTINATION string2
WITH TOP MARGIN = 2, TOP OF PAGE = "^L", PAGE LENGTH = 66

Here the caret (^) symbol specifies the CONTROL key; this is in contrast with other
4GL features (for example, the ON KEY clause) that use "CONTROL-" as the notation
to reference the CONTROL key.

If the WITH clause appears, its values override any corresponding parameter that
were explicitly stated in the OUTPUT section of the REPORT definition, or any default
values.

An implication of this feature is that any report can now use either top-of-page
character string processing or repeated blank lines to space to the page, depending on
what was specified when the report is started.

String Concatenation Operator

In all releases of 4GL, the comma (,) symbol has concatenation semantics in some
contexts for lists of strings (as in LET, PREPARE, and PRINT statements). Four J’s
BDL introduces a double-pipe ( || ) concatenation operator that accepts two values of
simple data types as operands, and joins them to return a single character-string
value.

Language Extensions 5-51

Equal Comparison Operator Synonym

In the right-hand side of the LET statement, or in the argument list of a function call,
the concatenation operator can join two values of any simple data type. It associates
its operands from left to right. Thus, ( a || b || c ) and ((a || b) || c ) are equivalent. Prece-
dence of this operator is higher than LIKE, MATCHES, or relational operators, but
lower than the arithmetic operators.

If either operand is a NULL string, then the returned value is NULL, represented as a
string of zero length. This is in contrast to how LET ignores NULL values within
comma-separated lists, unless every value in the list is NULL. (The NULL and LET
returns from a comma-separated list of NULL values is represented as a single blank
space.)

For example, if a and b are non-NULL strings, and c is NULL, then

LET x = a,b,c -- This assigns (a || b) to variable x.
LET y = a || b || c -- This assigns NULL to variable y.

In LET statements, you can choose between these two methods of treating NULL
values in concatenation by substituting || for comma if you want a NULL string
returned from any concatenation that includes a NULL operand.

In some contexts, only || can perform concatenation.

CALL myfunct ( a || b, c )

is not equivalent to
CALL myfunct (a, b, c)

because comma is always a list separator symbol in function calls.

Concatenation with the || operator discards trailing whitespace from operands of

integer and fixed-point number data types, but not from character or floating point
data types. The CLIPPED operator of 4GL can remove trailing blanks from values
before concatenation in 4GL statements, but TRIM must replace CLIPPED in prepa-
rable SQL statements (for Version 7.x and later Informix databases).

Equal Comparison Operator Synonym

The CONSTRUCT statement and Boolean expressions of 4GL support relational
operators that can perform comparisons of two data values.

5-52 Four J’s Business Development Language User Guide

Hiding the Comment Line

4GL supports "==" as a synonym for "=" (just as earlier releases have supported "!="
as a synonym for the "<>" operator.

For example, the expressions in the two statement fragments:

IF x = y THEN GO TO :finario
IF x == y THEN GO TO :finario

are equivalent.

Hiding the Comment Line

By default, the last line of the current 4GL window is the Comment line, which can
display messages that the COMMENT attribute of a 4GL form specifies. This is a
reserved line, which is cleared when the user moves the visual cursor to a new line of
a screen form, so it is typically used to send messages to the user, rather than for data
entry or data display. In 4GL forms that do not use the COMMENT attribute, the
Comment line is unused space on the screen.

Four J’s BDL enables you to conserve display space within a 4GL window by hiding
the Comment line. The new syntax that can appear within the ATTRIBUTE clause of
the OPEN WINDOW statement is:
COMMENT LINE OFF

This is supported by both 4GL 7.30 and by Four J’s BDL 3.0. If this is specified, then
the Comment line is hidden for that 4GL window and cannot display messages from
the form specification, even if some fields of a form that this window displays have
the COMMENT attribute.

Editing Multibyte Data in 4GL Forms

4GL 7.20 introduced GLS, a locale-based feature for supporting the entry, display,
retrieval, and collation of strings that include non-ASCII characters, as well as display
formats for number, time, and currency data for various languages and cultures
besides those of the default (U.S. English) locale. 4GL 7.x supports the Informix
locale files for most European and Asian languages, including multibyte East Asian
locales for Chinese, Japanese, and Korean languages.

Language Extensions 5-53

Editing Multibyte Data in 4GL Forms

4GL does not, however, support languages that use right-to-left or bidirectional text
(such as Arabic, Farsi, Hebrew, or Urdu).

Additional details about GLS can be found in the Informix Guide to GLS
Functionality.

The following environment variables can be set to support non-default character sets,
and cultural conventions for the display of numeric, date, and currency data values:

• CLIENT_LOCALE
• DBAPICODE
• DB_LOCALE
• DBNLS
• GL_DATE
• GL_DATETIME
• LANG
• SERVER_LOCALE

SQL identifiers that include non-ASCII characters that the locale of the database
supports can appear within SQL statements in 4GL source code, provided that the
locale of the 4GL client system also supports these non-ASCII characters in its
codeset.

4GL identifiers, data strings, and the values of CHAR, VARCHAR, and TEXT
variables, formal arguments, and returned values can include non-ASCII characters
that the current locale supports.

4GL forms can include locale-dependent characters as text, and fields can support
such characters in data entry and data display operations. For East-Asian locales that
support multibyte characters, this feature is new in Four J’s BDL. If a multibyte string
requires more bytes of storage than the declared size of a 4GL form field, or more than
a segment of a field, then the string is truncated from the right. Any partial character
that might be created by this truncation is replaced by whitespace.

When using a multibyte character set, the storage length (in bytes) can be longer than
the display length of the field in a form. For example, a form field that is declared
LIKE a CHAR(16) database column can hold a string of 16 multibyte characters which
actually occupies at least 32 bytes in the database.

5-54 Four J’s Business Development Language User Guide

Editing Multibyte Data in 4GL Forms

In locales whose codesets include multibyte characters, 4GL does not create partial
characters. In 4GL or SQL operations that attempt to divide a string within a multibyte
logical character, whitespace is substituted for any partial character. Examples of
operations in which whitespace automatically replaces any partial characters include
4GL expressions that include the substring ( [ ] ) operator, truncation of data strings
when they are stored in variables, and data entry into fields of 4GL forms in which
the length (in bytes) of the field is smaller than the length (in bytes) of the data string.

The following built-in functions and operators of 4GL can accept or return locale-
supported non-ASCII (and multibyte) characters, or can process multibyte characters
without creating partial characters:

• CLIPPED operator
• DOWNSHIFT( )
• LENGTH( )
• Substring ( [ ] ) operator
• UPSHIFT( )
• WORDWRAP operator

The built-in functions FGL_GETENV( ) and FGL_KEYVAL( ) cannot return

multibyte characters. (They can return single-byte non-ASCII characters that the
client locale supports.)

In Japanese locales, WORDWRAP fields in 4GL forms and in output from reports
perform single-pass kinsoku processing, for characters that the locale file lists as
prohibited from appearing at the beginning or end of a line. If a character that is
prohibited from ending a line appears at the end of a line, it is moved down to the
beginning of the next line. A character that precedes another that is prohibited from
beginning a line can similarly be moved down to the next line. (By single pass is
meant that each line is tested only once. Even if this process results in a line ending
in a forbidden character, no further kinsoku processing is performed.) The locale files
must identify the characters that are prohibited from beginning a line or prohibited
from ending a line.

Important: Four J’s BDL requires Client SDK 2.30 to support these GLS features.

Language Extensions 5-55

Commenting 4GL Extensions for Compatibility

Commenting 4GL Extensions for Compatibility

In Four J’s BDL, you can write:
--# CALL fgl_init4js()

The Four J’s BDL compiler treats the '--#' as whitespace and ignores it, compiling a
call to the fgl_init4js( ) function. 4GL sees the '--' as a comment indicator and treats
the rest of the line as a comment.

4GL 7.30 introduces an analog to this Four J’s BDL feature, providing a notation that
4GL treats as whitespace and ignores, compiling what follows as ordinary code, but
Four J’s BDL sees the line as a comment.

This is the notation:

--@

This allows the programmer to write:

--# OPTIONS HELP FILE "f4gl_help.42h" --Line is ignored by I-4GL
--@ OPTIONS HELP FILE "i4gl_help.iem" --Line is ignored by F-4GL

The previous two lines are the logical equivalent to the following logic:
--# IF TRUE THEN
--# OPTIONS HELP FILE "d4gl_help.42h"
--# ELSE
OPTIONS HELP FILE "i4gl_help.iem"
--# END IF

This is much more verbose and makes less clear what is intended.

Conditional comments are supported both in source (.4gl) files and in form specifi-
cation (.per) files. The following example shows a fragment of a form specification
that uses one attribute for the 4GL form compiler, and another for the Four J’s BDL
form compiler:
ATTRIBUTES
f0 = FORMONLY.name, --#char_var ;
--@REVERSE ;

They are also valid within SQL statement blocks but not within the text of a PREPARE
statement.

5-56 Four J’s Business Development Language User Guide

Informix BOOLEAN Data Type Support

These symbols are called conditional comment indicators because their effect
depends on whether you compile with the 4GL or Four J’s BDL compiler. Just as with
other comment indicators, they have no special significance within a quoted string.

Because the compilers treat a conditional comment as either whitespace or as a

comment, you cannot use both in the same line, as in this example:
CALL abc--#function()--@procedure()

Conditional comment indicators are treated as whitespace if the compiler does not
treat them as beginning a comment, so the previous example always generates a
compile-time syntax error, because neither 'CALL abc' (using 4GL) nor 'CALL abc
procedure()' (using Four J’s BDL) is valid code. When a conditional comment
indicator is interpreted as beginning a comment, the comment marker '--#' or '--@'
terminates the previous keyword or symbol.

Because "--@" is a new syntax feature of 4GL 7.30, it is treated as a comment symbol
by all previous releases of the 4GL (and Four J’s BDL) compilers, just as "--#" is
treated as a comment symbol in all 4GL releases.

Informix BOOLEAN Data Type Support

4GL uses the INTEGER data type for boolean expressions. INFORMIX Universal
Server introduces a new BOOLEAN data type which actually is a CHAR(1) where
the "t" and "f" values represent the TRUE and FALSE boolean values. These
"BOOLEAN" values cannot be used directly in 4GL boolean expressions.

Here is an example of 4GL code that raises a data type conversion error :
# Prerequisite : The database holds a table defined as :
# CREATE TABLE tab1 ( col1 BOOLEAN )
#
DATABASE stores
MAIN
DEFINE vbool INTEGER
LET vbool = ( 1 = 0 )
INSERT INTO tab1 VALUES( vbool )
END MAIN

-9634 No such cast.

The specified cast does not exist. Use the CREATE CAST statement
to define the cast.

Language Extensions 5-57

Informix BOOLEAN Data Type Support

The following functions are provided to convert INFORMIX Universal Server

"BOOLEAN" values to 4GL INTEGER booleans:

• fgl_charbool_to_intbool
Converts an Informix Universal Server BOOLEAN value ("t", "f") to a
4GL INTEGER value (TRUE, FALSE). The function returns NULL If
the given value does not match "T", "t", "F" or "f".
• fgl_intbool_to_charbool
Converts a 4GL INTEGER value to a CHAR(1) value to be stored in a
BOOLEAN column of an Informix Universal Server table. The func-
tion returns NULL if the given value is NULL.

The above example can be written as follows:

# Prerequisite : The database holds a table defined as :
# CREATE TABLE tab1 ( col1 BOOLEAN )
#
DATABASE stores
MAIN
DEFINE vbool CHAR(1)
LET vbool = fgl_intbool_to_charbool( 1 = 0 )
INSERT INTO tab1 VALUES( vbool )
END MAIN

On the other hand, when you retrieve a BOOLEAN values from the database, you can
convert that value with the fgl_charbool_to_intbool( ) as in the following example :
# Prerequisite : The database holds a table defined as :
# CREATE TABLE tab1 ( col1 BOOLEAN )
# and fglschema has been executed with the "-c" flag.
#
DATABASE stores
MAIN
DEFINE rtab1 RECORD LIKE tab1.*
SELECT * INTO rtab1.* FROM tab1
IF fgl_charbool_to_intbool( rtab1.col1 ) THEN
DISPLAY "TRUE"
ELSE
DISPLAY "FALSE"
END IF
END MAIN

5-58 Four J’s Business Development Language User Guide

Retrieving FGLPROFILE settings

Retrieving FGLPROFILE settings

The fgl_getresource function returns the value of an FGLPROFILE resource.

Syntax fgl_getresource (resname)

resname CHAR(*) the name of the fglprofile entry

Returns CHAR(*) the value of the resource

Warning: If the entry is not defined in fglprofile, the function returns NULL rather
than the default entry.

Example:
DEFINE def CHAR(100)
LET def = fgl_getresource ( "fglrun.defaults")

Warning: Users are free to add custom fglprofile entries but must take care when
choosing the resource names so as not to conflict with standard entries. It is strongly
recommended that custom fglprofile entries start with “custom.*”.

Language Extensions 5-59

Retrieving the Current Process Identifier

Retrieving the Current Process Identifier

To retrieve the system process identifier (pid) for the current program use the
fgl_getpid () function.

Syntax fgl_getpid()

returns INTEGER the process ID

Warning: On Windows platforms, this function will return a positive process id

number, simulating Unix behavior.

5-60 Four J’s Business Development Language User Guide

Chapter

Form Extensions
6
In This Chapter . . . . . . . . . . . . . . . . . . . . 6-3
List Boxes . . . . . . . . . . . . . . . . . . . . . . 6-4
Buttons . . . . . . . . . . . . . . . . . . . . . . . 6-6
Bitmaps . . . . . . . . . . . . . . . . . . . . . . . 6-11
Check Boxes . . . . . . . . . . . . . . . . . . . . . 6-12
Radio Buttons . . . . . . . . . . . . . . . . . . . . . 6-14
Button Fields . . . . . . . . . . . . . . . . . . . . . 6-15
Combo Box Fields . . . . . . . . . . . . . . . . . . . 6-16
Scrolling Fields . . . . . . . . . . . . . . . . . . . . 6-17
Folder Tabs . . . . . . . . . . . . . . . . . . . . . . 6-17
Form Labels . . . . . . . . . . . . . . . . . . . . . 6-19
Password Fields . . . . . . . . . . . . . . . . . . . . 6-21
6-2 Four J’s Business Development User Guide
In This Chapter
This chapter describes the 4GL language extensions that Four J’s BDL has added to
the form-specification files. Many widgets such as buttons, combo boxes and check
boxes are supported so forms can be displayed with a friendly, graphical user
interface.

Form Extensions 6-3

List Boxes

List Boxes
Screen arrays in graphical mode are displayed with list box objects. The following
code generates output in graphical mode, as Figure 6-8 shows:
DATABASE formonly
SCREEN {

[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]
[f01 ] [f02 ]

}
ATTRIBUTES
f01 = formonly.f01 type char;
f02 = formonly.f02 type char;
INSTRUCTIONS
SCREEN RECORD s_rec[10] (f01,f02)

Figure 6-8
Graphical Mode
Output

6-4 Four J’s Business Develpoment Language User Guide

List Boxes

If you want the fields to appear on individual lines, add the following string in the
attribute section of your fields in the form-specification file:
options="-nolist"

In the previous example, if you change the lines:

f01 = formonly.f01 type char;
f02 = formonly.f02 type char;

to match these:
f01 = formonly.f01 type char, options="-nolist";
f02 = formonly.f02 type char, options="-nolist";

you get the results that Figure 6-9 shows.

Figure 6-9
Graphical Mode
Output with Fields
on Separate Lines

You can also make fields appear on individual lines by including the following
setting in your fglprofile file:
gui.workSpaceFrame.nolist=1

Form Extensions 6-5

Buttons

This feature can be useful to keep the alignment of fields on forms. The list box
display type does not allow you to configure the colors of the object. The nolist
display type lets you control the color parameters.

Buttons
This section discusses extensions for menu buttons, hot-key buttons, and in-form
buttons.

Menu Buttons
The menu buttons created with the 4GL statements MENU … END MENU are
displayed as rows or columns of buttons. You can access these buttons by using
keyboard shortcuts, as with ASCII 4GL applications, or by clicking them.

To choose the positioning of the button on the screen, use the Menu.style resource
in the fglprofile configuration file, as follows:

Menu.style = 0 The menu is set on the top of the application window.

Menu.style = 1 The menu is set on the right frame of the application.

For more information about the fglprofile, see Chapter 5, “Language Extensions,”
and Appendix B, “Hints, Tips and Workarounds.”

Hot-Key Buttons
Hot keys that you define in COMMAND KEY or ON KEY statements are displayed in
a separate frame located on the right side of the application. These buttons automat-
ically appear when activated.

To access hot keys, press the corresponding key with the ASCII version of the appli-
cation or click the button with the mouse.

6-6 Four J’s Business Develpoment Language User Guide

Hot-Key Buttons

To edit the labels of hot-key buttons, use the following order of precedence, listed
from highest to lowest:

1. The KEY attributes in a field of a .per file. (You cannot change a label with
fgl_dialog_setkeylabel() if the same key attributes are present for a special
key.)
2. The fgl_dialog_setkeylabel() function
3. The KEYS section in a .per file
4. The fgl_setkeylabel function
5. The fglprofile file

Editing fglprofile
The $FGLDIR/etc/fglprofile configuration file contains a section where you can
define the label for each hot key. The name of this resource is:
key."key".text = label

where key is the name of the key (F1, CONTROL-V, …) and label is the label to use on
the button.

For example, the following entry in fglprofile changes the default label of the hot key
F7to the word Zoom:
key.f7.text = "Zoom"

The order of appearance of the hot key in the right frame is defined by the
key."key_name".order resource in fglprofile.

Editing the .per File

This method edits the KEYS section in the form-specification file (.per file). to
display the label of a hot-key button when the corresponding form is used. For
example:
--# KEYS
--# F1 = "HELP ON MASK"
--# F2 = "ZOOM"

The --# pattern is optional, but if specified, guarantees the compatibility of your
source code with INFORMIX-4GL.

Form Extensions 6-7

Hot-Key Buttons

Setting the KEY Field Attribute

This method uses the KEY field attribute in a form-specification file to change the
label of hot-key buttons when the cursor is in the corresponding field. Use the
following syntax:
ATTRIBUTES
f001 = customer.customer_num,
--# KEY F10 = "SEARCH",
--# KEY F11 = "CLEAR",
REVERSE;

In this example, when the cursor is in the field corresponding to the tag f001 of the
form, the labels of the F10 and F11 hot key buttons will be SEARCH and CLEAR.

Using 4GL Functions

This method uses calls to 4GL functions in 4GL source-code modules. These
functions are divided into the following two categories:

• Functions that execute during a dialog with the user; for example, during
INPUT, INPUT ARRAY, or CONSTRUCT.
• Functions that are not specific to the current user dialog.

To retrieve the text associated with a given hot-key for the current open form, use the
fgl_dialog_getkeylabel () function.

Syntax fgl_dialog_getkeylabel (keyname)

keyname CHAR (*) the name of the hot-key

returns CHAR(*) the text associated with this key

If you want to change a label for a specific user dialog, use the
fgl_dialog_setkeylabel() function. Use the following syntax:
fgl_dialog_setkeylabel("key", "label")

6-8 Four J’s Business Develpoment Language User Guide

Hot-Key Buttons

To retrieve the text associated with a given hot-key as a global setting, use the
fgl_getkeylabel () function.

Syntax fgl_getkeylabel (keyname)

keyname CHAR (*) the name of the hot-key

returns CHAR(*) the text associated with this key

If you want to change the label outside a specific user dialog, you must do so before
the beginning of the dialog statement. Use the following syntax:
fgl_setkeylabel(hot_key_name, new_label)

hot_key_name The name of the hot key to change the label

new_label The new label displayed on the hot-key button

The names of the keys are case sensitive. The names of the keyboard function keys
are in lowercase: f1, f2, f3, and so on. For example:
...
BEFORE INPUT
CALL FGL_SETKEYLABEL ("f4", "About")
INPUT BY NAME f01,f02
ON KEY (f4)
CALL DISPLAY_ABOUT( )
END INPUT
...

The label of the f4 hot-key button displayed by the ON KEY statement will be About.
The user can click the About button displayed on the right side of the application
window or press F4 to execute the DISPLAY_ABOUT function (undefined in this
example).

With these methods, if you set the label to the empty string " ", the buttons will
either disappear from the application window or leave an empty button in the key
frame, depending on a resource in fglprofile.

Form Extensions 6-9

Buttons in the Form

An empty button does not react to mouse clicks. This behavior is defined in the
fglprofile configuration file with the following resource:
gui.empty.button.visible = 1 The button remains visible but does not
react to mouse clicks. This is the default
value.
gui.empty.button.visible = 0 The button becomes invisible and disap-
pears.

This feature does not influence the behavior of the application, however. Even if a
hot-key button does not appear, the user can execute the action defined by an ON KEY
statement by pressing the corresponding key on the keyboard.

Buttons in the Form

Buttons can be added to the screen section of a form. To do so, add a field tag to the
screen section and add the widget and the config string in the attribute definition of
the tag. The widget parameter must be set to BUTTON and the config parameter must
be set to the name of the key sent to the application when the button is pressed. The
following code creates a form with two buttons displayed at the bottom of the form.

In a 4GL module, add the following lines:

.
.
.
OPEN WINDOW w AT 2,3 WITH FORM "button" ATTRIBUTE(BORDER)

DISPLAY "Insert/Overwrite" TO bt1

DISPLAY "Zoom" TO bt2

INPUT BY NAME a,b,c

DISPLAY "" TO bt1 # erases label and deactivates the button.

DISPLAY "" TO bt2 # erases label and deactivates the button.

6-10 Four J’s Business Develpoment Language User Guide

Bitmaps

Create this form-specification file, button.per:

DATABASE formonly
SCREEN {
Field1 [a]
Field2 [b]
Field3 [c]
[bt1 ] [bt2 ]
}
ATTRIBUTES
a = formonly.a;
b = formonly.b;
c = formonly.c;
bt1 = formonly.bt1
--# , widget="BUTTON", config="Control-a"
;
bt2 = formonly.bt2
--# , widget="BUTTON", config="F1"
;
end
--#KEYS
--#"F1"=""

With this example, during the INPUT statement, you can click the two buttons. The
first one will send the CONTROL-A key. This key toggles the insert and overwrite
modes. The second button sends the F1 key.

Bitmaps
To add a picture to a form, create a field tag in the screen section of a form and add
the widget and config string to the attribute definition of the tag. In this case, the
widget parameter must be set to BMP and the config parameter must be set to the
name of the bitmap file to be displayed and to the name of the key to send to the appli-
cation when the bitmap is clicked.

The width of the field tag in the screen section of the form must be at least as wide as
the name of the bitmaps that will be used, or it will not be possible to change them
with the DISPLAY TO statement.

Form Extensions 6-11

Check Boxes

Check Boxes
Check boxes are used for making binary choices. Each check box controls a single
variable. Check boxes in a group are not mutually exclusive options.

In ASCII mode (with the FGLGUI environment variable set to 0), check boxes are
displayed as normal input fields.

Syntax
In form-specification files, check boxes are defined in the same manner as plain
fields but the attribute definition of the field has more options. In the following
example, two check boxes are displayed.

In the file check.per:

DATABASE FORMONLY
SCREEN {

CheckBox 1: CheckBox 2:
[chk01 ] [chk02 ]

}
ATTRIBUTES
chk01 = formonly.chk01, default="str_on"
--# , widget="CHECK", config="str_on str_off str_lab"
;
chk02 = formonly.chk02, default="No"
--# , widget="CHECK", config="Yes No acknowledge"
;
end

The --# sequences are optional and are only designed to preserve compatibility with
INFORMIX-4GL.

In the attribute section of the file, set the widget option to CHECK to use check
boxes.

The config option contains three parameters. The first parameter is the value returned
by the check box when it is activated, the second when it is deactivated and the third
is the label displayed to the right side of the check box.

If you do not specify a default value, the check box is set to a null string.

6-12 Four J’s Business Develpoment Language User Guide

Invoking a Key Code

Important: The length of the string returned by an active check box must be at least
as long as the one returned when it is set to be inactive or the check box will behave
unpredictably. In the example above, the strings for chk02 are “Yes” and “No”, if
these were changed to “Ja” and “Nein” the check box will not work as “Ja” is a
shorter string than “Nein”.

Invoking a Key Code

You can send a single key instead of a string when you invoke a check box. The
option class=”key” must be added in the attribute section of the declaration of the
check box in the form file, as the following example shows:
DATABASE FORMONLY
SCREEN
{
Key Check 1 : [f05 ] [f06 ]
}
ATTRIBUTES
f05=formonly.f05, class="key", widget="CHECK",
config="F1 F6 {Check #1}";
f06=formonly.f06, class="key", widget="CHECK",
config="F2 F7 {Check #2}";

In this example, the field f05 will send key F1 when activated and F6 when
deactivated.

You can also activate or deactivate check boxes in 4GL programs, but only the one
from the key class. In order to activate a check box, use the following statement
(replacing myButton with the name of a check box in the current form):
DISPLAY "!" TO myButton

And to deactivate it use:

DISPLAY "*" TO myButton

If you activate a default class check box type outside of an input statement, it will
appear checked but you will be unable to use it.

Form Extensions 6-13

Radio Buttons

Radio Buttons
Radio buttons provide a way to select one of several mutually exclusive options. Sev-
eral radio buttons work together to control a single variable.

In ASCII mode (with the FGLGUI environment variable set to 0), the radio buttons
and are displayed as standard Informix fields.

Syntax
The definition of radio buttons uses the same options as that of check boxes. The
following example displays frames that include three radio buttons.

In the file radio.per:

DATABASE formonly
screen {

radiobutton:
[rad001 ]

}
attributes

rad001 = formonly.rad001, default="str_one"

--# ,widget="RADIO", config="str_one lab_one str_two lab_two
str_three lab_three"
;
end

To use radio buttons, set the widget attribute to RADIO. The config option is built in
the following way; the str_one string is returned if the first radio button of the frame
is selected, the str_two string is the value returned for the second button, the lab_one
string is the string used for the label of the first button and lab_two for the second
button.

The value returned by the radio button is a null string if no button is selected in the
frame. It is possible to define a default value for the radio button group.

6-14 Four J’s Business Develpoment Language User Guide

Invoking a Key Code

Invoking a Key Code

You can send a single key instead of a string when you invoke a radio button. The
option class=”key” must be added in the attribute section of the declaration of the
radio button in the form file, as the following example shows:
DATABASE FORMONLY
SCREEN
{
Key Radio 1 :
[f08 ]

}
ATTRIBUTES
f08=formonly.f08, class="key", widget="RADIO",
config="F11 {Radio #1} F12 {Radio #2}
F13 {Radio #3}";

In this example, the three choices of the radio button f08 will send F11, F12, or F13.

You can also activate or deactivate radio buttons in 4GL programs, but only the one
from the key class. To activate a radio button, use the following statement (replacing
myButton with the name of a radio button in the current form):
DISPLAY "!" TO myButton

And to deactivate it use:

DISPLAY "*" TO myButton

If you activate a default class radio button type outside of an input statement, it will
appear checked but you will be unable to use it.

Button Fields
The button field object is an association between a classical field and a bitmap (bmp
field) on its left side. It is possible to give a value to the field or to click the bitmap
to send a specified key. The bmp fields do not require any changes to the 4GL source
code to be added.

The field definition has two more attribute parameters: widget and config.

The widget parameter should be set to FIELD_BMP to indicate the type of field.

Form Extensions 6-15

Combo Box Fields

The config string is the name of the bitmap file with a .bmp extension and the name
of the key sent to the application when the bitmap is clicked. The bitmap file must be
in $FGLDIR/bmp or in $FGLDIR/toolbars. The default values are
$FGLDIR/toolbars/combo.bmp for the bitmap file name and F1 for the key. The size
of the bitmap is constant, so a large bitmap will be truncated. For example:
DATABASE formonly
screen {
[bmf001 ]
}
attributes
bmf001 = formonly.bmp_field, widget="FIELD_BMP", config="combo.bmp
Control-q";

Combo Box Fields

A combo box field is one with a down arrow button on the right hand side that drops
down a list of fixed values from which the user can select.

The Combo Box Field is defined as follows:

f001 = formonly.f001,
widget=”COMBO”,
include=(<value-list>);

The following example defines three fields on a form - the first a normal field, the
second a normal field with an include and the third a Combo Box field.
database formonly
screen {
Normal field : [f001 ]
Normal field with include : [f002 ]
Combo field : [f003 ]
}
attributes
f001 = formonly.field1;
f002 = formonly.field2,
include=("AAA","BBB","CCC","DDD");
f003 = formonly.field3, widget="COMBO",
include=("AAA","BBB","CCC","DDD");

6-16 Four J’s Business Develpoment Language User Guide

Scrolling Fields

Scrolling Fields
A field shorter than the corresponding program variable can be scrolled during input
if the scroll attribute has been added to its definition in the form file. For example:

• In the .4gl file:

MAIN
DEFINE text CHAR(512)
OPEN WINDOW w1 AT 1,1 WITH FORM "demo1"
INPUT BY NAME text
CLOSE WINDOW w1
END MAIN
• In the .per file:
SCREEN
{
Short entry: [f001 ]
}
ATTRIBUTES
f001 = formonly.text type char
--#, scroll
;
END
INSTRUCTIONS
DELIMITERS " "
END

This would allow scrolling within the field up to the full length of the variable.

Folder Tabs
Folder tabs allow you to create tabs that display different parts of a form. For
example, you might divide a form for entering information into three subforms that
you can display by clicking a folder tab.

Important: You do use an input statement on fields located on different subforms.

To use this feature, add more than one SCREEN section in a form. To set the label in
the folder tab, use the following syntax:
SCREEN TITLE "label"
{
...
}

Form Extensions 6-17

Folder Tabs

with the label appearing as the name of the folder tab.

The following example shows how to create folder tabs with two files, demo1.per
and demo1.4gl. The “input” and “input array” options display a form as three
subforms. The input is done through three fields on the first two subforms and the
input array is done on the third subform.

File demo1.per :
DATABASE formonly
SCREEN TITLE "screen 1/3"
{
field 1 [f01 ]
field 2 [f02 ]
}
SCREEN TITLE "Screen 2/3"
{
field 3 [f03 ]
}
SCREEN TITLE "Screen 3/3"
{
Array row 1 [a01 ]
Array row 2 [a01 ]
Array row 3 [a01 ]
Array row 4 [a01 ]
}
ATTRIBUTES
f01 = formonly.f01;
f02 = formonly.f02;
f03 = formonly.f03;
a01 = formonly.a01;
INSTRUCTIONS
screen record scr_arr[4] (a01)

6-18 Four J’s Business Develpoment Language User Guide

Form Labels

File demo1.4gl:
MAIN

DEFINE f01,f02,f03 CHAR(20)

DEFINE arr ARRAY[10] OF RECORD

a01 CHAR(10)
END RECORD

OPEN FORM frm1 from "demo1"

MENU "Folder tabs"

COMMAND "Input"
OPEN WINDOW w1 AT 3,1 WITH 25 rows, 80 columns
DISPLAY FORM frm1
INPUT BY NAME f01, f02, f03
CLOSE FORM frm1
CLOSE WINDOW w1

COMMAND "Input array"

OPEN WINDOW w1 AT 3,1 WITH 25 rows, 80 columns
DISPLAY FORM frm1
INPUT ARRAY arr from scr_arr.*
CLOSE FORM frm1
CLOSE WINDOW w1

COMMAND "Exit"
EXIT MENU

END MENU

END MAIN

Form Labels
Form Labels allow you to internationalize 4GL forms by displaying strings dynami-
cally from the 4GL program, with the DISPLAY TO or DISPLAY BY NAME
instructions.

Form Labels are defined by using the same syntax as form fields, with the
WIDGET="LABEL" option in the attribute list.

Form Extensions 6-19

Form Labels

Example

The "names.per" form has the following specification :

DATABASE FORMONLY
SCREEN
{
Last Name [F01 ]
First Name [F02 ]
}
ATTRIBUTES
F01=formonly.F01;
F02=formonly.F02;

The "names.4gl" file is as follows:

MAIN

DEFINE F01, F02 CHAR(20)

OPEN WINDOW wi AT 1,1 WITH FORM "names"

INPUT BY NAME F01, F02

END MAIN

The following code modifies this example to set the "Last Name" and "First Name"
strings from the 4GL program according to a menu selection.

The "names.per" form is modified as follows:

DATABASE FORMONLY
SCREEN
{
[L01 ] [F01 ]
[L02 ] [F02 ]
}
ATTRIBUTES
F01=formonly.F01;
F02=formonly.F02;
L01=formonly.L01, WIDGET="LABEL";
L02=formonly.L02, WIDGET="LABEL";

6-20 Four J’s Business Develpoment Language User Guide

Password Fields

The "names.4gl" file is modified as follows:

MAIN

DEFINE F01, F02 CHAR(20)

DEFINE L01, L02 CHAR(10)

OPEN WINDOW wi AT 1,1 WITH FORM "names"

MENU "Names"
COMMAND "English"
LET L01="First Name"
LET L02="Last Name"
EXIT MENU

COMMAND "Francais"
LET L01="Prenom"
LET L02="Nom"
EXIT MENU

END MENU

DISPLAY BY NAME L01

DISPLAY BY NAME L02

INPUT BY NAME F01, F02

END MAIN

Password Fields
Password fields in a form allow entered input to be masked with “*” characters. This
would normally be used to hide the entry of a password from a Windows dialog.

To set up a password field, use the widget class=”PASSWORD”.

Example
f001 = formonly.password, class=”PASSWORD”

Form Extensions 6-21

Password Fields

6-22 Four J’s Business Develpoment Language User Guide

Chapter

Graphical Extensions
7
In This Chapter . . . . . . . . . . . . . . . . . . . . 7-3
Display Extensions . . . . . . . . . . . . . . . . . . . 7-3
Four J’s Business Development Language Library Initialization . . . . 7-3
Check User Interface Type. . . . . . . . . . . . . . . . 7-4
Checking for Graphical User Interface usage . . . . . . . . . . 7-5
Checking for Windows Client Mode . . . . . . . . . . . . 7-6

Window-Management Functions . . . . . . . . . . . . . . . 7-8

Setting the Size of the Application Container . . . . . . . . . . 7-8
Setting the Title of the Application Container . . . . . . . . . . 7-8
Retrieving Information from a Field . . . . . . . . . . . . . 7-9
Retrieving Application Window Properties . . . . . . . . . . 7-10
Setting the Current Window . . . . . . . . . . . . . . . 7-11
Closing a Window by Name . . . . . . . . . . . . . . . 7-12
Clearing a Window by Name. . . . . . . . . . . . . . . . 7-12

Dialog Boxes . . . . . . . . . . . . . . . . . . . . . 7-13

Creating an Interactive Message Box . . . . . . . . . . . . 7-13
Displaying an Interactive Message Box. . . . . . . . . . . . 7-14
Formatting Text in a Message Box . . . . . . . . . . . . . 7-15
Entering a Field Value into a Message Box . . . . . . . . . . 7-16

Multiple Document Interface (MDI) Support . . . . . . . . . . . 7-17

MDI Configuration. . . . . . . . . . . . . . . . . . . 7-18
Toolbars . . . . . . . . . . . . . . . . . . . . . . . 7-19
Statusbars . . . . . . . . . . . . . . . . . . . . . . 7-24
Output redirection.. . . . . . . . . . . . . . . . . . . . 7-25
Drawing Extensions . . . . . . . . . . . . . . . . . . . 7-29
Mouse-Management Functions . . . . . . . . . . . . . . 7-29
Returning a Value After a Left Mouse Click . . . . . . . . . 7-29
Returning a Value After a Right Mouse Click . . . . . . . . 7-30
Remove Key Binding . . . . . . . . . . . . . . . . 7-30
Defining the Drawing Area . . . . . . . . . . . . . . . 7-30
Initializing the Drawing Function. . . . . . . . . . . . . . 7-31
Selecting a Drawing Area . . . . . . . . . . . . . . . . 7-32
Selecting a Drawing Color . . . . . . . . . . . . . . . . 7-33
Specifying the Text Insertion Point . . . . . . . . . . . . . 7-33
Changing Line Colors . . . . . . . . . . . . . . . . . 7-34
Setting Line Width . . . . . . . . . . . . . . . . . . 7-34
Clearing the Draw Function . . . . . . . . . . . . . . . 7-34
Drawing Rectangles . . . . . . . . . . . . . . . . . . 7-35
Drawing an Oval . . . . . . . . . . . . . . . . . . . 7-35
Drawing a Circle . . . . . . . . . . . . . . . . . . . 7-36
Drawing a Line . . . . . . . . . . . . . . . . . . . 7-36
Drawing Text . . . . . . . . . . . . . . . . . . . . 7-37
Drawing an Arc . . . . . . . . . . . . . . . . . . . 7-37
Drawing a Polygon . . . . . . . . . . . . . . . . . . 7-38

7-2 Four J’s Business Development Language User Guide

In This Chapter
This chapter describes functions that can be used to enhance the graphical user
interface (GUI). Toolbars or Statusbars can be added to the screen along with the
ability to display charts with the drawing functions.

Display Extensions
This section describes an initialization function and other functions that relate to
display environments.

Four J’s Business Development Language Library

Initialization
The following function is required at the beginning of every 4GL program that calls
functions from the Four J’s BDL libraries:

Syntax fgl_init4js()

For example:
--#CALL fgl_init4js()

Check User Interface Type

The following function returns a CHAR() string defining the current user interface
type.

Graphical Extensions 7-3

Check User Interface Type

Syntax fgl_getuitype()

Returns CHAR(*) string defining the current type of user interface

“CHAR” = ASCII terminal interface

“WTK” = MS Windows TCL/TK user interface

“XTK” = X Windows TCL/TK user interface

“JAVA” = JAVA based user interface

“HTML” = HTML based user interface

For some GUI types, the function performs a network round trip. To improve perfor-
mance, it is NOT recommended that this function is performed inside a loop .

For Example:
DEFINE uitype CHAR(5)
DEFINE i INTEGER
LET uitype = fgl_getuitype()
FOR i=1 TO 100
IF uitype = “CHAR” THEN
...
ELSE
...
END IF
END FOR

7-4 Four J’s Business Development Language User Guide

Checking for Graphical User Interface usage

Checking for Graphical User Interface usage

The following function returns the current value of the FGLGUI environment
variable:

Syntax fgl_fglgui()

Returns TRUE if the program is run under a GUI

FALSE if the program is run on an ASCII terminal

For example:
MAIN
--#CALL fgl_init4js()
IF fgl_fglgui() = 1 THEN
CALL fgl_winmessage ("Welcome from server to WTK",
"nice to meet you!!", "info")
ELSE
OPEN WINDOW w1 AT 1,1 WITH 5 ROWS, 50 COLUMNS ATTRIBUTE (BORDER)
DISPLAY "Welcome from server to ASCII " AT 2, 5
SLEEP 3
CLOSE WINDOW w1
END IF
END MAIN

Compile this program with the Four J’s BDL compiler and execute it. Figure 7-1
shows the message that appears if you are in ASCII mode for UNIX.
Figure 7-1
Welcome
Message
in ASCII Mode

Tip: If you execute this program with UNIX, be sure to put a SLEEP statement after
DISPLAY so that you can see the message.

Graphical Extensions 7-5

Checking for Windows Client Mode

Figure 7-2 shows the message that appears if you are in graphical mode.
Figure 7-2
Welcome
Message
in Graphical Mode

Checking for Windows Client Mode

The following function tells you if the graphical front end used is the Windows Front
End:

Syntax fgl_wtkclient()

Returns TRUE if displayed on a Windows Front End;

FALSE if displayed on an X-Windows Front End or ASCII terminal

7-6 Four J’s Business Development Language User Guide

Checking for Windows Client Mode

The following program tests whether you are using the GUI and, if so, whether you
are using Windows:
MAIN
--#CALL fgl_init4js()

IF fgl_fglgui() = 1 THEN

IF fgl_wtkclient() = 1 THEN

CALL fgl_winmessage ("Welcome from server to WTK",

"Pleased to meet you!!", "stop")

ELSE

CALL fgl_winmessage (" Welcome from server to X",

"Nice to meet you!!", "info")

END IF

ELSE

OPEN WINDOW w1 AT 1,1 WITH 5 ROWS, 50 COLUMNS ATTRIBUTES

(BORDER)
DISPLAY "Welcome from server to ASCII " AT 2, 5
SLEEP 1
CLOSE WINDOW w1

END IF

END MAIN

After compiling and executing the program, you have the two windows as in the
fgl_fglgui examples. Figure 7-3 shows the message that you see if you are using an
X-Windows client.
Figure 7-3
Welcome
Message
in Windows Client
Mode

Graphical Extensions 7-7

Window-Management Functions

Window-Management Functions
This section describes the extensions that help you manage application windowing.

Setting the Size of the Application Container

The following function allows you to change the default size of the program window.
Syntax fgl_setsize (nblines, nbcols)

nblines Integer that specifies the new number of lines

nbcols Integer that specifies the new number of columns

Example:
…
IF answer = "yes" THEN
IF reduce_flag THEN
--#CALL fgl_setsize(25,80) #normal size
ELSE
--#CALL fgl_setsize(10,50) #reduced size
LET reduce_flag = TRUE #reduced size
END IF
END IF
…

Setting the Title of the Application Container

The following function allows you to set the title of a program window:
Syntax fgl_settitle(mytitle)

mytitle String or variable with the new title

The default title is the program name. To change this title, use the fgl_settitle
function.

7-8 Four J’s Business Development Language User Guide

Retrieving Information from a Field

Example:
MAIN
DEFINE title CHAR(100),
flag SMALLINT
--#CALL fgl_init4js()
--#CALL fgl_settitle("hello world")
LET flag = TRUE
WHILE flag
PROMPT "Give the new title: " FOR title
--#CALL fgl_settitle(title)
IF TITLE = "#" THEN
LET flag = FALSE
END IF
END WHILE
END MAIN

With this example, enter the new title of the window into the title field and then press
ENTER. To quit this program, press the interrupt key.

Retrieving Information from a Field

The following function allows you to receive information about the currently
prompted field during a dialog function:

Syntax call fgl_formfield_getoption ("option") returning var

option x Returns the X position of current field in the form

y Returns the Y position of current field in the form
length Returns the length of current field in the form

var The variable containing the return value of the function

Example:
…
INPUT by name f01
BEFORE INPUT
LET LGT = fgl_formfield_getoption("length")
MESSAGE "No more than ",LGT," charaters"
END INPUT
…

Graphical Extensions 7-9

Retrieving Application Window Properties

Retrieving Application Window Properties

The following function returns information about the current application window:

Syntax call fgl_window_getoption ("option") returning var

option name Returns the name of the current window

x Returns the X position of the current window

y Returns the Y position of the current window

width Returns the width of the current window

height Returns the height of the current window

border Returns TRUE if the current window has a border; oth-
erwise returns FALSE

formline Returns the form line of the current window

menuline Returns the menu line of the current window

commentline Returns the comment line of the current window

messageline Returns the message line of the current window

errorline Returns the error line of the current window

insertkey Returns the value of insertkey (value as with the
fgl_getkey function)

deletekey Returns the value of deletekey (value as with the

fgl_getkey function)

nextkey Returns the value of nextkey (value as with the

fgl_getkey function)

previouskey Returns the value of previouskey (value as with the

fgl_getkey function)

acceptkey Returns the value of acceptkey (value as with the

fgl_getkey function)

helpkey Returns the value of helpkey (value as with the

fgl_getkey function)

7-10 Four J’s Business Development Language User Guide

Setting the Current Window

abortkey Returns the value of abortkey (value as with the

fgl_getkey function)

inputwrap Returns TRUE if the inputwrap option is on;

otherwise returns FALSE

fieldorder Returns TRUE if the fieldorder option is constraint;

otherwise returns FALSE

var The variable that contains the return value of the function

Example:
MAIN
DEFINE VAR CHAR(20)
CALL fgl_init4js()
OPEN WINDOW hello AT 2,2 WITH 20 ROWS, 50 COLUMNS
ATTRIBUTES(BORDER)
LET var = fgl_window_getoption("name")
DISPLAY "You are in window ",var AT 5,5
SLEEP 3
CLOSE WINDOW hello
END MAIN

Setting the Current Window

The following function makes the specified window, named name, the active
window:

Syntax fgl_window_current("name")

name Specifies the name of a window

Example:
Call fgl_window_current("hello")

Graphical Extensions 7-11

Closing a Window by Name

Closing a Window by Name

The following function closes the window called winname:

Syntax fgl_window_close("winname")

winname CHAR(*) The name of the window to close

Example:
CALL fgl_window_close("winname")

Clearing a Window by Name.

The following function clears the window called winname even if it is not the current
window:

Syntax fgl_window_clear ("winname")

winname CHAR(*) The name of the window to clear

Example:
CALL fgl_window_clear("winname")

7-12 Four J’s Business Development Language User Guide

Dialog Boxes

Dialog Boxes
This section describes the extensions that affect dialog boxes.

Creating an Interactive Message Box

The following function displays an interactive box in a separate window with all
possible answers in a menu:

Syntax fgl_winbutton (title, text, default, buttons, icon,

danger)

title Title of the box

text Text of the question (\n stands for new line)

default Default button selected

buttons List of values separated by the pipe character (|)

icon Name of the icon to be used in the dialog box

Figure 7-4 shows possible message icon selections.

Figure 7-4
Possible Configuration Message Icons

Info Exclamation Question Stop

danger Number of the warning item: a skull with crossbones will appear
each time the pointer enters the corresponding button (on X11 only)

You can put anything in the definition of a button, subject to the following rules:

• If you declare a button with a sentence as the label, you cannot put spaces
between each word, otherwise one button will be created for each word.

Graphical Extensions 7-13

Displaying an Interactive Message Box

• You can declare a maximum of 7 buttons with 10 characters each per call.

Displaying an Interactive Message Box

The following function opens a dialog box with all possible answers in a menu:

Syntax fgl_winquestion (title, text, default_value,

possible_values, icon, danger)

title Title of the dialog box

text Text of the question (\n stands for new line)

default_value Answer on which the focus has to be positioned

possible_values List of values separated by the pipe character (|)

Figure 7-5 shows sample message values.

Figure 7-5
Message Values
Possible Configuration

French German English

Ok or “” Ok or “” Ok or “”

Oui|Non|Interrompre Ja|Nein|Unterbrechen Yes|No|Cancel

Oui|Non Ja|Nein Yes|No

Ok|Interrompre Ok|Unterbrechen Ok|Cancel

or or
Ok|Annuler Ok|Interrupt

Abandon|Repeter|Ignorer Abbrechen|Wiederholen| Abort|Retry|

Übergehen Ignore

Repeter|Interrompre Wiederholen|Unterbrechen Retry|Cancel

7-14 Four J’s Business Development Language User Guide

Formatting Text in a Message Box

icon Name of the icon to be used in the dialog box

danger Number of the warning item: a skull with crossbones will appear each time
the pointer enters the corresponding button (on X11 only)

Returns Text of the chosen answer

The following program shows you how to use the fgl_winquestion function:
MAIN
DEFINE answer CHAR(100)
--#CALL fgl_init4js()
--#LET answer = fgl_winquestion ("Title of the dialog box",
"Question Text", "Yes", "Yes|No|Cancel", "question",1 )
END MAIN

This code produces the dialog box that Figure 7-6 shows.
Figure 7-6
Dialog Box

This function replaces the typical PROMPT...FOR CHAR loop.

Formatting Text in a Message Box

The following function formats a message and presents it in a separate window:.

Syntax fgl_winmessage (title, text, icon)

title Title of the message box

text Text of the message

icon Name of the icon to be used in the message box

Graphical Extensions 7-15

Entering a Field Value into a Message Box

This function displays a message box with an OK button. For example:

MAIN
--#CALL fgl_init4js()
--#CALL fgl_winmessage("Title of the message", "Text or variable", "info")
END MAIN

This code produces the message box that Figure 7-7 shows.
Figure 7-7
Message Box

Entering a Field Value into a Message Box

The following function displays a dialog box with a field that accepts a value:

Syntax fgl_winprompt (x, y, text, default, length, type)

x, y Position of the prompt window

text Text of the question

default Not currently used

length Length of the entry

type Input data type code: (0=char, 1=smallint, 2=integer, 7=date,

255=invisible).

Returns Entered value

7-16 Four J’s Business Development Language User Guide

Multiple Document Interface (MDI) Support

The following example shows how to use this function:

MAIN
DEFINE name CHAR(10)
--#CALL fgl_init4js()
--#CALL fgl_winprompt(5, 2, "Give me your name please", "", 10, 0)
returning name
--#CALL fgl_winmessage("Answer", name, "info")
END MAIN

This code produces the dialog box that Figure 7-8 shows.
Figure 7-8
Dialog Box with
Entry Field

Multiple Document Interface (MDI) Support

This section describes MDI configuration for 4GL applications.

Graphical Extensions 7-17

MDI Configuration.

MDI Configuration.
Each 4GL program defines which MDI container it is to be displayed in through
fglprofile settings. Several MDI containers may be created to group 4GL programs.

The use of an MDI interface is optional, it can be activated by setting:

gui.containerType = “{mdi|sdi}”
gui.containerName = “<id>”

where “id” is the user defined name for the MDI. If gui.containerName is undefined
or defined as “default”, the 4GL application will be displayed in a Single Document
Interface (SDI) container. By this method, each MDI window is identified by a
unique name.

By default, the toolbar and statusbar configuration is taken from the SDI settings
(gui.toolbar.* and gui.statusbar.*). For more information on these settings see
“Toolbars” on page 7-19 and “Statusbars” on page 7-24.

Specific settings can be defined for each MDI window using the following entries:
gui.mdi.<id>.window.title = “<title>”

where “title” is the MDI container title. Default = “id”.

gui.mdi.<id>.window.autoclose = {true|false}

This defines whether the container should be closed automatically after the last appli-
cation window has been closed. Default = true.

7-18 Four J’s Business Development Language User Guide

Toolbars

Toolbars
You can add a toolbar at the top of the screen that contains icons representing hot
keys or menu options. When the buttons are clicked with the mouse, the hot key or
menu option is actioned. A help tip appears when the mouse pointer is positioned
over an icon.

To enable tool bar functionality, add the following line to fglprofile:

gui.toolBar.visible = true

To disable the toolbar, add the following line:

gui.toolBar.visible = false

To define the root path to the images used on the toolbar buttons, use the
gui.directory.images entry in fglprofile.

gui.directory.images = “path”

Entry Description

gui.directory.images defines where the images for the toolbar are stored.
Defaults are:
$WTKDIR\images\ for the Windows client
$FGLDIR\images\ for the X11 client

Following this line, add any or all of the following toolbar configuration entries:

gui.toolbar.size = {“small”|“medium”|“large”}
gui.toolbar.button.width = <integer>
gui.toolbar.style = {“relief”|“flat”}
gui.toolbar.showTexts = {true|false}

These entries define the toolbar itself and are defined as follows:

Graphical Extensions 7-19

Toolbars

Entry Description

gui.toolbar.size Defines the size of the toolbar buttons and the subdirectory where
the images are to be found.
“small” = 16X16 pixels, images are found in
gui.directory.images/small
“medium” = 32X32 pixels images are found in
gui.directory.images/medium
“large” = 48X48 pixels images are found in
gui.directory.images/large
Default is “small”

gui.toolbar.button.width Defines the width of the toolbar buttons in characters

Default is the size of the largest image

gui.toolbar.style Defines the style of the toolbar. Options are “relief” or “flat”
Default is “relief”

gui.toolbar.showtexts Indicates whether button labels are visible. Options are True or
False.
Default is False

7-20 Four J’s Business Development Language User Guide

Toolbars

After the toolbar configuration entries, add the entries to configure the individual
buttons on the toolbar. All these entries are in the format:
gui.toolbar.<n>.*

where n is the number of the toolbar button.

gui.toolbar.<n>.image.file = “<bmpname>.bmp”
gui.toolbar.<n>.label = “<string>”
gui.toolbar.<n>.comments = “<hint>”
gui.toolbar.<n>.hideButton = {true|false}

(The following two entries are mutually exclusive - coding both will give unpre-
dictable results).
gui.toolbar.<n>.text = “<menuoption>”
gui.toolbar.<n>.key = “<hotkey>”

Graphical Extensions 7-21

Toolbars

Element Description

.image.file = "<bmpname>.bmp" Bitmap file to be displayed in the toolbar button.

The file bmpname.bmp must exist in the directory
defined in gui.directory.images

.label = "string" Defines the text which is shown below the image
on the toolbar button. If this is not defined, the
default label is the text of the .text or the .key
option.

.comments = "hint" Defines the bubble help text to be displayed over

the toolbar button.

.hideButton = {true|false} Used to hide the control frame key button

corresponding to the toolbar button (does NOT
hide the toolbar button).
Default is false.

.text = "menuoption" Defines the 4GL menu option to be called when

the button is selected. Must not be used when the
.key option is coded

.key = "hotkey" Defines the hot-key to be returned when the button

is selected. Must not be used when the .text option
is coded

7-22 Four J’s Business Development Language User Guide

Toolbars

When setting the text, key or bmp properties to fglSeparator, a space will be
displayed at the given position. fglSeparator allows you to group toolbar buttons.

The following example shows a fglprofile configuration file for a Windows client:
gui.directory.images = “c:/wtkhome/my_pictures”

gui.toolbar.visible = true
gui.toolbar.size = “medium”
gui.toolbar.1.text = "add"
gui.toolbar.1.image.file = "adduser.bmp"
gui.toolbar.1.hidebutton = true
gui.toolbar.2.key = "interrupt"
gui.toolbar.2.image.file = "stop.bmp"
gui.toolbar.2.hidebutton = true
gui.toolbar.3.text = "fglSeparator"
gui.toolbar.3.image.file = "fglSeparator"
gui.toolbar.4.text = "help"
gui.toolbar.4.image.file = "ques.bmp"
gui.toolbar.4.hidebutton = true

This configuration file generates a toolbar with three icons. The first icon activates
the “add” option on the menu. The second icon sends an interrupt signal to the appli-
cation. The third icon, separated slightly from the others, activates the help function.

Graphical Extensions 7-23

Statusbars

Statusbars
This section describes how to create a statusbar within an application.

A statusbar can be displayed at the bottom of an application window or MDI

container. The statusbar is divided into panels which are customizable to display 4GL
output (e.g. MESSAGE, ERROR), keyboard status (e.g. CAPS LOCK) and the
client/server communication status. The panels can be adjusted by the client so that
the panel is always the same size as the “textOn” attribute of the indicator.

Application and MDI status bars cannot be mixed. When a 4GL application is
displayed in an MDI, no application statusbar is shown, only the MDI statusbar is
visible.

Configuration:
Statusbars are defined in fglprofile. If there are no statusbar entries no statusbar is
displayed - there is no default configuration within the client.

To show/hide the statusbar, set the following entry:

gui.statusbar.visible = {true|false}

To define the statusbar panels, use the following entries:

gui.statusbar.panel.<pid>.position = <integer>

where <pid> is the statusbar panel identifier used by output redirection entries and
position defines the relative location of the panel within the statusbar. Positions start
at 1 from the left and -1 from the right. For instance:
gui.statusbar.panel.p1.position = 1
gui.statusbar.panel.p2.position = 2
gui.statusbar.panel.p3.position = -1
gui.statusbar.panel.p4.position = -2

7-24 Four J’s Business Development Language User Guide

Output redirection.

will give the following results:

| Panel 1 | Panel 2 | Panel 4 | Panel 3|

gui.statusbar.panel.<pid>.width = <integer>

Where “width” is the size of the panel in characters. A zero width causes automatic
sizing.
gui.statusbar.panel.<pid>.bordered = {true|false}

To display information in the statusbar, redirect the 4gl output or the keyboard status
to the panels using the gui.display.* entries. See “Dialog Boxes” on page 7-13

Output redirection.
To redirect the output from a 4GL statement or the keyboard status, use the
gui.display.* fglprofile entries.

gui.display.<source>.destination = “<destination>”
gui.display.<source>.color = “<color>”
gui.display.<source>.image = “<image>”
gui.display.<source>.beep = “{true|false}”
gui.display.<source>.texton = “<texton>”
gui.display.<source>.textoff = “<textoff>”
gui.display.<source>.boxtitle = “<boxtitle>”
gui.display.<source>.boxicon = “<boxicon>”

Graphical Extensions 7-25

Output redirection.

<source> defines the source of the redirection. Values can be one of:
error ERROR instruction

message MESSAGE instruction

menucomment MENU instruction comments

fromcomment Form Field comments

keycomment Key comments

kbnumlock Num Lock indicator

kbscrlock Scroll Lock Indicator

kbcaplock Caps Lock indicator

kboverwrite Overwrite indicator

waitapp Communication state

7-26 Four J’s Business Development Language User Guide

Output redirection.

“destination” defines the redirection destination. Values can be one of:

default Default redirection, e.g. for ERROR it would be the standard 4GL
error line

tooltip On a tool tip

messagebox In a messagebox dialog

statusbar.<pid> In a statusbar panel

The following attributes are dependent on <source>. For example, “error” redirection
can use the “beep” attribute but “kbnumlock” cannot.

“color” defines the text color, for instance errors may be displayed in red.

“image” specifies a picture to be displayed when the output is redirected. For

instance, errors may have a warning image.

beep defines if a beep is to be generated when the output is redirected

“texton” defines the text for “on” status (especially for keyboard states) e.g. :
“CAPS”, “NUM”, “OVR”

“textoff” defines the text for “off” status e.g. “INS”

“boxtitle” defines the text used for the title messages

“boxicon” defines the icon displayed in the message box. Values can be one of the
following:
“iconasterisk”
“iconexclamation”
“iconhand”
“iconinformation”
“iconquestion”
“iconstop”

Graphical Extensions 7-27

Output redirection.

The following is an example of redirection of common 4GL output and keyboard

status:
gui.display.error.destination = “statusbar.p1”
gui.display.error.color = “red”
gui.display.error.iamge = “error.bmp”
gui.display.error.beep = true

gui.display.formcomment.destination = “statusbar.p2”

gui.display.keycomment.destination = “statusbar.p2”

gui.display.kbcapslock.destination = “statusbar.p3”
gui.display.kbcapslock.texton = “CAPS”

gui.display.kbnumlock.destination = “statusbar.p4”
gui.display.kbnumlock.texton = “NUM”

gui.display.kboverwrite.destination = “statusbar.p5”
gui.display.kboverwrite.texton = “OVR”
gui.display.kboverwrite.textoff = “INS”

gui.display.menucomment.destination = “tooltip”

gui.display.message.destination = “messagebox”
gui.display.message.color = “yellow”
gui.display.message.image = “warning.bmp”
gui.display.message.beep = true

7-28 Four J’s Business Development Language User Guide

Drawing Extensions

Drawing Extensions
A set of new functions allows you to draw simple shapes. You will be able to insert
lines, rectangles, ovals, circles, texts, arcs, and polygons in a defined area. You will
also be able to bind a keystroke with the right or left click of the mouse on any of the
items in the drawing.

Mouse-Management Functions
Before you begin drawing, you might want to specify the behavior of your mouse. To
manage mouse behavior, use the following functions.

Returning a Value After a Left Mouse Click

To define a key to be returned when you click the left mouse button, use the following
function:

Syntax drawbuttonleft(obj_noobj_no, key)

obj_no INTEGER Item number returned by the function creating the object.

key CHAR(xx) The name of the key to be returned when you click an item with
the left mouse button.

Returns None

This function defines a key to be returned when you click the specified item with the
left mouse button. For example:
CALL drawbuttonleft(num_item,"F4")

Graphical Extensions 7-29

Defining the Drawing Area

Returning a Value After a Right Mouse Click

To define a key to be returned when you click the right mouse button, use the
following function:

Syntax drawbuttonright(obj_no, key)

obj_no INTEGER Item number returned by the function creating the object

key CHAR(xx) The name of the key to be returned when you click an item with
the right mouse button

Returns None

For example:
CALL drawbuttonright(num_item, "Control-c")

Remove Key Binding

The following function removes all key binding on an item:

Syntax: drawclearbutton(obj_no)

obj_no INTEGER Item number returned by the function creating the object

Returns None

For example:
CALL drawclearbutton(num_item)

Defining the Drawing Area

The drawing area is defined in the same way as a screen array, as the following
example shows.

7-30 Four J’s Business Development Language User Guide

Initializing the Drawing Function

In the file draw2.per:

DATABASE FORMONLY
SCREEN {

Enter the percentage of blue.

The rest will be filled with green.
BLUE [f01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]

}
ATTRIBUTES
f01 = formonly.blue;
c01 = formonly.draw,widget="Canvas";

The only difference is in the attributes section of the form. You must add the option
widget="Canvas" (the "Canvas" string is case sensitive).

Initializing the Drawing Function

The following function is the initialization function:

Syntax drawinit()

Returns None

To use drawings in a 4GL program, insert the following line at the beginning of your
program, before the first display open statement:
CALL drawinit()

This function loads the graphical add-on to your client computer. If you call this
function after you open the form that contains the canvas, calls to the canvas
functions will produce no results the first time that you run your application after
starting the client daemon.

Graphical Extensions 7-31

Selecting a Drawing Area

Selecting a Drawing Area

The following function selects an area in which to draw:

Syntax drawselect(field_name)

field_tag CHAR(xx) Field name in which you want to draw

Returns None

After a window that contains a form with one or more drawing areas is opened, select
the area in which you want to draw. All the drawing areas have fixed resolutions of
1000 by 1000 points. The 0,0 coordinate of the area is at the lower left corner, and
the 1000,1000 coordinate is at the upper right corner. For example:
CALL drawselect("draw")

Important: Before version 3.00.1e of the compiler the canvas drawing area was
referenced by the tag name specified in the form specification file. Since version
3.00.1e, the field name should be used to reference the canvas area. In order to keep
the same 4GL code, just modify the form specification files by using the same name
for the field and the field tag.
Example:
DATABASE FORMONLY
SCREEN {
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
[c01 ]
}
ATTRIBUTES
c01 = formonly.mycanvas,widget="Canvas";

To be compatible, the field definition :

c01 = formonly.mycanvas,widget="Canvas";

becomes:
c01 = formonly.c01,widget="Canvas";

7-32 Four J’s Business Development Language User Guide

Selecting a Drawing Color

Selecting a Drawing Color

The following function specifies the drawing color:

Syntax drawfillcolor(color)

color CHAR(xx) Name of the color

Returns None

This function sets the fill color for all drawings. This function must be set before the
drawing function. The color will remain active until another color is chosen. The
color name list is located in the file named rgb.txt, located in the $FGLDIR/desi/etc/
directory on UNIX and in the desi\etc\ subdirectory of the Windows front-end instal-
lation directory. For example:
CALL drawfillcolor("red")

Specifying the Text Insertion Point

The following function specifies the insertion point for the text:

Syntax drawanchor(pos)

pos CHAR(x) n Top center of the text

e Right side
s Bottom center of the text
w Left side

Returns None

Use drawAnchor() to specify the origin point for the text before using the function
drawtext. For example:
CALL drawanchor("n")

Graphical Extensions 7-33

Changing Line Colors

Changing Line Colors

The following function defines whether the color of the line can change:

Syntax disablecolorlines(colorLines)

colorLines INTEGER 0 The lines take the color defined by

DrawFillColor
1 The lines are always black
Returns None

By default, the lines take the color defined by the DrawFillColor function.

Example:
CALL disablecolorlines(1)

Setting Line Width

The following function specifies the width of the line:

Syntax drawlinewitdth(width)

width INTEGER Width of the line in pixels

Returns None

You can set the width of the line before using the DrawLine function. For example:
CALL drawlinewidth(2)

Clearing the Draw Function

The following function is the clear function:

Syntax drawclear()

Returns None

7-34 Four J’s Business Development Language User Guide

Drawing Rectangles

This function clears the drawing area specified by the drawselect function. For
example:
CALL drawclear()

Drawing Rectangles
The following function draws a rectangle by specifying the lower left corner and the
length:

Syntax drawrectangle(x,y,h,w)

x,y INTEGER Coordinate of the lower left corner

h,w INTEGER Height and width of the rectangle

Returns The item number of the rectangle in the canvas

The rectangle is filled with the color set using the function drawfillcolor.

For example:
CALL drawrectangle (500,400,120,110) RETURNING ret

Drawing an Oval
The following function draws an oval:

Syntax drawoval(y,x,dy,dx)

x,y INTEGER Coordinate of the lower left corner

h,w INTEGER Height and width of the rectangle that contains the
oval

Returns The item number of the oval in the canvas

This function draws an oval in a bounding rectangle. The rectangle is defined in the
same way as with the drawrectangle function. The oval is filled with the color set
using the function drawfillcolor. For example:
CALL drawoval(500,400,150,100) RETURNING ret

Graphical Extensions 7-35

Drawing a Circle

Drawing a Circle
The following function draws a circle:

Syntax drawcircle(x,y,r)

x,y INTEGER The lower left corner of the bounding square that con-
tains the circle

r INTEGER The border length (effectively, the diameter)

Returns The item number of the circle in the canvas

This function draws a circle in a bounding square, specifying the lower left corner of
the square and the border length. The circle is filled with the color set using the
function drawfillcolor. For example:
CALL drawcircle(500,400,65) RETURNING ret

Drawing a Line
The following function draws a line:

Syntax drawline(y,x,dy,dx)

x,y INTEGER Coordinate of the first point of the line

dx,dy INTEGER Coordinate increment to the second point of the

line.

Returns The item number of the line in the canvas

This function draws a line from start point to end point using the
drawlinewidth function. The line is filled with the color set using the function
drawfillcolor. For example:
CALL drawline(500,400,300,500) RETURNING ret

7-36 Four J’s Business Development Language User Guide

Drawing Text

Drawing Text
The following function draws text: This function draws the specified string from the
Syntax drawtext(y,x,t)

x,y INTEGER The origin point of the text

t CHAR(xx) The string to draw from the origin point

Returns The item number of the text in the canvas

specified coordinate. By default, the origin point will be the centre point of the text.
Use the drawanchor function to justify the text. For example:
CALL drawtext(500,400, "Hello world!!!") RETURNING ret

Drawing an Arc
The following function draws an arc:

Syntax drawarc(x,y,d,start,arc)

x,y INTEGER The coordinate of the lower left corner

d INTEGER The border length

start INTEGER The start angle

arc INTEGER The span of the arc

Returns The item number of the arc in the canvas

Graphical Extensions 7-37

Drawing a Polygon

This function draws an arc of a circle bounded by a square. You can specify the lower
left corner of the square, its border length, the start angle of the arc in degrees, and
the span of the arc in degrees. The line is filled with the color set using the function
drawfillcolor. For example:
CALL drawarc(500,400,100,12,25) RETURNING ret

Drawing a Polygon
The following function draws a polygon:

Syntax drawpolygon(list)

list CHAR(xx) List of coordinates

Returns The item number of the polygon in the canvas

This function draws a filled polygon defined by the list of points. The list must
contain at least three points. To separate points, use spaces rather than commas. For
example:
CALL drawpolygon("120 150 200 150 400 430") RETURNING ret

7-38 Four J’s Business Development Language User Guide

Chapter

The Configuration File

8
In This Chapter . . . . . . . . . . . . . . . . . . . . 8-4
The Four J’s Business Develpoment Language Configuration File . . . . 8-4
Global Configuration File . . . . . . . . . . . . . . . . 8-4
User Configuration File. . . . . . . . . . . . . . . . . 8-5
Program Configuration File . . . . . . . . . . . . . . . 8-5

General Configuration . . . . . . . . . . . . . . . . . . 8-6

Runtime Configuration . . . . . . . . . . . . . . . . . . 8-6
General . . . . . . . . . . . . . . . . . . . . . . 8-6
UNIX . . . . . . . . . . . . . . . . . . . . . . 8-9
Microsoft Windows . . . . . . . . . . . . . . . . . . 8-10

License Configuration . . . . . . . . . . . . . . . . . . 8-13

General . . . . . . . . . . . . . . . . . . . . . . 8-13
UNIX . . . . . . . . . . . . . . . . . . . . . . 8-16

Graphical User Interface . . . . . . . . . . . . . . . . . . 8-17

General . . . . . . . . . . . . . . . . . . . . . . 8-17
fglrun.interface . . . . . . . . . . . . . . . . . . 8-17
Graphical Daemon Autostart . . . . . . . . . . . . . . . 8-19
Menu . . . . . . . . . . . . . . . . . . . . . . 8-20
Screen GUI Settings . . . . . . . . . . . . . . . . . . 8-21
Key GUI Settings . . . . . . . . . . . . . . . . . . 8-24
Windows GUI Settings . . . . . . . . . . . . . . . . . 8-30
Local Editing Settings . . . . . . . . . . . . . . . . . 8-31
Cut, Copy, and Paste Feature Settings . . . . . . . . . . . . 8-32
Memory Mapping Settings . . . . . . . . . . . . . . . . . 8-34
8-2 Four J’s Business Development Language User Guide
The Configuration File 8-3
The Four J’s Business Develpoment Language Configuration File

In This Chapter
This chapter describes all the settings available in the configuration file. For each
setting, this chapter provides a description, possible values, and an example of the
syntax. The configuration file has the following sections:

• The Four J’s BDL Configuration file

• General configuration
• Global configuration
• License configuration
• Graphical User Interface
• Memory mapping

The Four J’s Business Develpoment Language

Configuration File
You can control the behavior of the Four J’s BDL compiler with the following three
configuration files:

• Global configuration file

• User configuration file
• Program configuration file

Global Configuration File

The main configuration file, fglprofile, is located in the $FGLDIR/etc directory. This
configuration file is loaded first and is loaded each time you run an application.

8-4 Four J’s Business Development Language User Guide

User Configuration File

User Configuration File

The user configuration file is specified by the FGLPROFILE environment variable.
If this environment variable is set in the environment of the current user, the corre-
sponding file is loaded after the fglprofile file. Entries defined in the two files are set
to the value defined by the last loaded configuration file.

Program Configuration File

The program configuration file is located in the directory defined in one of the two
previous configuration files with the entry named fglrun.default. (It is usually in the
$FGLDIR/defaults directory.) Use this configuration file to control program-specific
behavior.

The Four J’s Business Develpoment Language Configuration File 8-5

General Configuration

General Configuration
This section describes the settings for the general section of the configuration file.

fglrun.defaults
Description Specifies from which directory the program-specific configuration
files will be searched for.

Value Complete path to the specific configuration files

Default $FGLDIR/defaults

Syntax fglrun.defaults="$FGLDIR/defaults/"

Runtime Configuration
This section describes the settings that affect runtime configuration.

General
This section describes the general settings for the runtime section of the configuration
file.

fglrun.arrayIgnoreRangeError
Description Ignores range control in arrays. When this variable is set to 1,
if x is an array, x[-1] gives no error but returns NULL. If this
variable is set to 0, x[-1] gives error –1326.

Value 0 or 1

8-6 Four J’s Business Development Language User Guide

General

Default 0

Syntax fglrun.arrayIgnoreRangeError=1

Recommendation Set to 1

dialog.fieldOrder
Description Determines whether the intermediate event triggers (AFTER/BEFORE
FIELD/ROWS) are to be executed or not when moving from one field
to another using the mouse. If set to 1, the intermediate event triggers
are executed. If set to 0, the intermediate event triggers are not exe-
cuted.

Value 0 or 1

Default 1

Syntax dialog.fieldorder=0

report.aggregateZero
Description Determines the value to be returned by report aggregate functions
(avg, sum, ...) when the result is NULL.

Value 0 returns NULL

1 returns ZERO

Default 0

Syntax report.aggregateZero=0

The Four J’s Business Develpoment Language Configuration File 8-7

General

gui.chartable
Description Defines a conversion file to be used for characters under GUI. It will
be searched for in the $FGLDIR/etc/ directory. You can create a file
with the mkchartab utility (see Appendix C).

Value The path from the $FGLDIR directory to the filter file

Default None

Syntax gui.chartable="iso/ansinogr"

fglrun.cursor.global
Description With a 7.x Informix database, you can choose the scope range for cur-
sors at runtime. By default, the scope is local to the module (as in
INFORMIX-4GL 4.x).

Value 0 for local scope

1 for global scope

Default 0

Syntax fglrun.cursor.global=0

fglrun.ix6
Description Commands the P-code runner (fglrun) to act like INFORMIX-4GL 6.x.
For more information, see Chapter 6, “Form Extensions.”

Value 0 to react like INFORMIX-4GL 4.x

1 to react like INFORMIX-4GL 6.x

Default 0

Syntax fglrun.ix6=0

8-8 Four J’s Business Development Language User Guide

UNIX

UNIX
This section describes the settings specific to UNIX configurations.

fglrun.signalOOB
Description To send the interrupt signal to the server from the client, OOB data is
sent over the network. On some UNIX systems, the number of the OOB
data might be different from the default used by Four J’s BDL. In this
case, you can use this resource to test the signal number and then,
when identified, to specify it.

Value 0 receive the default signal when an OOB signal is sent to the pro-
gram
-1 test the signal received when an OOB signal is sent to the program

>0 receive a value when an OOB signal is sent to the program

Default 0

Syntax fglrun.signalOOB=0

The Four J’s Business Develpoment Language Configuration File 8-9

Microsoft Windows

Microsoft Windows
This section describes the settings specific to Windows configurations.

fglrun.cmd.winnt
Description Specifies the shell command to run for the RUN WITHOUT WAITING
statement on Windows NT.

A trailing space is required after the command.

Value Name of the command to execute

Default cmd /c

Syntax fglrun.cmd.winnt="cmd /c "

fglrun.cmd.win95
Description Shell command to perform the RUN WITHOUT WAITING command
on Windows 9x.

A trailing space is required after the command.

Value Name of the command to execute

Default start /m

Syntax fglrun.cmd.win95="start /m "

8-10 Four J’s Business Development Language User Guide

Microsoft Windows

fglrun.remote.envvar
Description In Windows, specifies the name of the variable used to distinguish a
remote connection from a network drive solution. If the runner finds
this variable on Windows NT, it will export the following two envi-
ronment variables to the database:

INFORMIXSERVICE (default turbo)

INFORMIXPROTOCOL (default olsoctcp)

Value Name of the variable to distinguish remote connection from network

drive

Default REMOTEADDRESS

Syntax fglrun.remote.envvar="REMOTEADDRESS"

The Four J’s Business Develpoment Language Configuration File 8-11

Microsoft Windows

fglrun.database.listvar
Description This variable must be set on Windows NT computers using
Informix database servers 7.2x and higher. It contains the list of all
Informix variables. On Windows NT, those variables will be exported
to the database environment, not to the process environment and not
to the child processes.

Important: Several environment variables cannot be retrieved by the

Four J's Dynamic Virtual Machine and by the Four J’s BDL. This
problem is due to Informix GLS version 3.0 API functions and to our
internal initialization function. The following environment variables
cannot be managed from the configuration file:

• DBDATE
• DB_LOCALE
• DBCENTURY
• DBMONEY
• DBFORMAT
• CLIENT_LOCALE
• INFORMIXDIR
• SERVER_LOCALE

Instead of setting those variables in the fglprofile file, please set them
directly in the environment using the command 'set':
c:\> set INFORMIXDIR=c:\informix

Value The complete list of Informix variables

Default "CC8BITLEVEL COLLCHAR CONRETRY CONTIME DBANSIWARN

DBDATE DBLANG DBMONEY DBNLS DBPATH DBTEMP DBTIME
DELIMIDENT ESQLMF FET_BUFF_SIZE GL_DATE GL_DATETIME
INFORMIXDIR INFORMIXSERVER INFORMIXSQLHOSTS LANG
LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
DBALSBC DBAPICODE DBASCIIBC DBCENTURY DBCODESET
DBCONNECT DBCSCONV DBCSOVERRIDE DBCSWIDTH DBFLTMSK
DBMONEYSCALE DBSS2 DBSS3"

8-12 Four J’s Business Development Language User Guide

License Configuration

fglrun.setenv.x
Description Sets an environment variable to a specific value even if the variable is
already defined. For each environment variable, increment the value
of x by 1, to create distinct resource names.

Value Name and value of the environment variable to set

Default None

Syntax fglrun.setenv.0="INFORMIXDIR=c:\informix"

fglrun.defaultenv.x
Description Specifies the default value of an environment variable. If a variable is
not found in the environment, this value will be exported. You need to
define at least INFORMIXDIR, INFORMIXSQLHOSTS, INFORMIX-
SERVER, and INFORMIXHOST (name of computer on which the
Informix database server runs) to use a remote session on
Windows NT. Increment the value of x by 1 to create distinct resource
names.

Value Name and value of the environment variable to set

Default None

Syntax fglrun.defaultenv.0="INFORMIXSQLHOSTS=\\IXSERVER"

License Configuration
This section describes the settings that affect licensing.

General
This section describes the general settings for the license section of the configuration
file.

The Four J’s Business Develpoment Language Configuration File 8-13

General

fgllic.server
Description Name of the computer that runs the license service program. You
must set this value to use the license server.

Value Name of the license server

Default None

Syntax fgllic.server="ixserver"

fgllic.service
Description Service port number to use for communication between the client and
the license server.

Value Port number

Default 6399

Syntax fgllic.service="7000"

8-14 Four J’s Business Development Language User Guide

General

fgllic.local
Description How the license data will be managed.

Value 0 if all data will be managed by the license server

1 if all data will be managed by the client

Default 0

Syntax fgllic.local=0

fgllic.ping
Description Time limit for the ping to detect the license server computer by a cli-
ent. If you use a distant network (by RTC or ISDN), you must increase
this value.

Value Time unit in milliseconds

Default 3000

Syntax fgllic.ping=5000

The Four J’s Business Develpoment Language Configuration File 8-15

UNIX

UNIX
This section describes settings that are specific to licensing on UNIX systems.

fgllic.check
Description Number of license verifications between two controls of the active
user list. Only used on UNIX systems.

Value Number of verifications before checking.

Default Value stored in $FGLDIR/lock/data/fglcheck

Syntax fgllic.check="10"

fgllic.ps
Description Command giving the list of processes running on the computer. The
FGLPS environment variable has a higher priority.

Value Command name and flag for listing all processes that run on a com-
puter

Default ps -ae

Syntax fgllic.ps="ps -ae"

8-16 Four J’s Business Development Language User Guide

Graphical User Interface

Graphical User Interface

This section describes the settings that affect configuration of the Graphical User
Interface (GUI).

General
This section describes general GUI configuration settings.

fglrun.interface
Description Specifies which interface configuration file the graphical daemon
should use. This file must be located in the $FGLDIR/etc/ directory.

Do not change this value.

Value Resource filename

Default fgl2c.res

Syntax fglrun.interface="fgl2c.res"

fglrun.scriptname
Description Specifies which Tcl/Tk script is loaded when you execute the first
4GL program after the graphical daemon is started. It will search in the
$FGLDIR/etc/ directory.

Do not change this value.

Value Tcl/Tk script file

Default fgl2c.tcl

Syntax fglrun.scriptname="fgl2c.tcl"

The Four J’s Business Develpoment Language Configuration File 8-17

General

gui.useOOB.interrupt
Description Enables or disables the OOB signal mechanism. If the TCP/IP stack of
the client computer (especially Windows computers) does not support
the OOB mechanism you must disable it. In this case, a second,
slightly more time-consuming method is used.

Value 0 disables the OOB signal on the TCP stack. No interruption signal
can be sent from the client machine to the 4gl application.
1 enables the OOB signal on the TCP stack

Default 1

Syntax gui.useOOB.interrupt = 1

Sleep.minTime
Description Specifies the minimum time (in seconds) before the interrupt button
appears when you use the SLEEP statement.

Value Number of seconds

Default 3

Syntax Sleep.minTime = 5

gui.key.radiocheck.invokeexit
Description Specifies the name of a key that, if pressed when the focus is on a
radio button or a check box, invokes the currently selected control and
then immediately goes to the next field. It can also be set to empty
string ("").

Value Key name

Default "Return"

Syntax gui.key.radiocheck.invokeexit = "Return"

8-18 Four J’s Business Development Language User Guide

Graphical Daemon Autostart

Graphical Daemon Autostart

This section describes the settings that control the start-up of the graphical daemon.

fglrun.server.cmd
Description Specifies the command used to start the GUI daemon (fglX11d).

Value Command to start the graphical daemon

Default fglX11d –A for UNIX systems
fglsserv for Windows

Syntax fglrun.server.cmd="fglsserv"

fglrun.server.number
Description Specifies the maximum number of graphical servers to autostart.

Default 100

Syntax fglrun.server.number=50

fglrun.server.x
Description With X11 , Citrix Winframe, and Microsoft Terminal Server client
computers, it is possible to autostart the graphical daemon on the
server when a 4GL program is executed.

If FGLSERVER is defined, values specified in it will be used first. The

variable DISPLAY (or WINSTATIONNAME for Winframe) deter-
mines which number of the daemon to use.

Value The client name and port number

Default None

Syntax fglrun.server.1="client:0, client:0.0"

The Four J’s Business Develpoment Language Configuration File 8-19

Menu

Menu
This section describes the menu settings in the GUI section of the configuration file.

Menu.style
Description Specifies the display style for the menu.

Value 0 Create normal horizontal menu

1 Create a menu as a button in the right key button frame on top of
the hot-key buttons

Default 0

Syntax Menu.style=0

gui.menu.timer
Description Time (in milliseconds) before the menu is disabled. Useful when you
switch between windows.

Value Number of milliseconds

Default 100

Syntax gui.menu.timer=100

8-20 Four J’s Business Development Language User Guide

Screen GUI Settings

Screen GUI Settings

This section describes the screen layout settings in the GUI section of the configu-
ration file.

gui.screen.size.x
Description Width of the screen in characters.

Value Number of characters

Default 80

Syntax gui.screen.size.x = 100

gui.screen.size.y
Description Height of the screen in characters.

Value Number of characters

Default 25

Syntax gui.screen.size.y = 40

gui.screen.x
Description X position of an application window.

Value incr An incremented position (In this case, you have to set
gui.screen.incrx).
center Centers the window in the screen
number An absolute position, in characters

Default incr

Syntax gui.screen.x = "incr"

The Four J’s Business Develpoment Language Configuration File 8-21

Screen GUI Settings

gui.screen.incrx
Description Specifies the increment for the display of the application windows (in
number characters) on the horizontal axis.

Value Number of characters

Default 3

Syntax gui.screen.incrx = 3

gui.screen.y
Description Y position of an application window.

Value incr An incremented position (In this case, you have to set
gui.screen.incry.)
center Centers the window in the screen
number An absolute position, in characters

Default: incr

Syntax gui.screen.y = "incr"

gui.screen.incry
Description Specifies the increment for the display of the application windows.

Value Number of characters

Default 2

Syntax gui.screen.incry = 3

8-22 Four J’s Business Development Language User Guide

Screen GUI Settings

gui.screen.withwm
Description Specifies if the window can be managed by the user.

Value 0 The main window will be ignored by the window manager. The
user will not be able to manipulate the window using the normal
window manager mechanisms like move and resize.
1 Normal mode

Default 1

Syntax gui.screen.withwm = 0

The Four J’s Business Develpoment Language Configuration File 8-23

Key GUI Settings

Key GUI Settings

This section describes the key code settings in the GUI section of the configuration
file.

gui.key.add_function
Description Specifies the offset for the code sent by SHIFT-F1. If the specified
value is 12, the code sent for SHIFT-F1 is F13. If the specified value is
10, the code sent for SHIFT-F1 is F11.

Value Offset for the key code SHIFT-F1

Default 12

Syntax gui.key.add_function=12

gui.key.interrupt
Description Specifies the key to be used to send the interrupt event to the 4GL
application.

Warning : “Control-c” cannot be used as a normal key when it is not

defined as interruption key.

Value Name of the interrupt key

Default "Control-c"

Syntax gui.key.interrupt = "Delete"

gui.key.doubleClick.left
Description Specifies the key code sent to the program when the left mouse button
is double-clicked.

Value Name of the key code to be sent to the program

Default "KEY_accept"

Syntax gui.key.doubleClick.left = "F30"

8-24 Four J’s Business Development Language User Guide

Key GUI Settings

gui.key.click.right
Description Specifies the key code sent to the program when the right mouse but-
ton is clicked.

Value Name of the key code to be sent

Default "F36"

Syntax gui.key.click.right = "F20"

gui.key.0.translate
Description Allows you to map one key to another. If a key is remapped to an
empty string, this disables the key. Use the file key.tcl to test your
keys.

Value Name of the key and the returned new value

Default None

Syntax gui.key.0.translate = "KP_Decimal comma"

Using the Key.tcl Script

This file is located in the $FGLDIR/etc directory. This script allows you to test the
value mapped to a key.

For the X11 Client, start the $FGLDIR/etc/key.tcl script with the following UNIX
statement:
$ owish -f key.tcl

For the Windows client:

1. Copy key.tcl script to your local drive.

2. Create a new icon.
For instance, copy the WTK server and edit the icon properties.
3. In the Command line, add the following:
c:\fgl2cusr\bin\wtk.exe -d -f <path_name>\key.tcl
where <path_name> is the path to key.tcl on your local drive.

The Four J’s Business Develpoment Language Configuration File 8-25

Key GUI Settings

After you start the key.tcl script, type the key or key combinations. Their ASCII value
and name are displayed in the debug window or in the terminal.

For example:
owish -f $FGLDIR/etc/key.tcl
Control_L 66
Control-c 56
Up 91
Down 92
Right 97
Left 87
Delete 84
KP_Enter 116
KP_3 111
KP_Decimal 112
Shift_R 65
Shift-exclam 10

key."key_name".text
Description The label, rather than the value, of a hot key to be displayed in the
right button frame.

Value Text for the specific key

Default key.help.text = Help

key.accept.text = OK
key.interrupt.text = Interrupt
key.delete.text = Delete
key.insert.text = Insert
key.return.text = Return
key.escape.text = Escape

The following table lists keys for specific actions.

Key Description

key.help.text Text for the help key

key.accept.text Text for the accept key

key.interrupt.text Text for the interrupt key

key.delete.text Text for the delete key

8-26 Four J’s Business Development Language User Guide

Key GUI Settings

Key Description

key.insert.text Text for the insert key

key.return.text Text for the return key

key.escape.text Text for the escape key

key.prevpage.text Text for the previous page key

key.nextpage.text Text for the next page key

The following table lists the function keys.

key.f1.text = F1 key.f13.text = F13

key.f2.text = F2 key.f14.text = F14

key.f3.text = F3 key.f15.text = F15

key.f4.text = F4 key.f16.text = F16

key.f5.text = F5 key.f17.text = F17

key.f6.text = F6 key.f18.text = F18

key.f7.text = F7 key.f19.text = F19

key.f8.text = F8 key.f20.text = F20

key.f9.text = F9 key.f21.text = F21

key.f10.text = F10 key.f22.text = F22

key.f11.text = F11 key.f23.text = F23

key.f12.text = F12 key.f24.text = F24

The Four J’s Business Develpoment Language Configuration File 8-27

Key GUI Settings

The following table lists the Control modified keys.

key.control-a.text = Control-a key.control-n.text = Control-n

key.control-b.text = Control-b key.control-o.text = Control-o

key.control-c.text = Control-c key.control-p.text = Control-p

key.control-d.text = Control-d key.control-q.text = Control-q

key.control-e.text = Control-e key.control-r.text = Control-r

key.control-f.text = Control-f key.control-s.text = Control-s

key.control-g.text = Control-g key.control-t.text = Control-t

key.control-h.text = Control-h key.control-u.text = Control-u

key.control-i.text = Control-i key.control-v.text = Control-v

key.control-j.text = Control-j key.control-w.text = Control-w

key.control-k.text = Control-k key.control-x.text = Control-x

key.control-l.text = Control-l key.control-y.text = Control-y

key.control-m.text = Control-m key.control-z.text = Control-z

8-28 Four J’s Business Development Language User Guide

Key GUI Settings

key."key_name".order
Description Specifies an order of appearance for keys. Each key has a unique pri-
ority number. The key with the lowest priority number is displayed on
the top of the right key button frame.

Value Order number for the specified key name

Default help 100

accept 101

interrupt 102

insert 103

delete 104

return 105

f1 106

f2 107

. .

. .

. .

f69 174

control-a 175

control-b 176

. .

. .

. .

control-z 200

escape 202

Syntax key.f1.order = 1002

The Four J’s Business Develpoment Language Configuration File 8-29

Windows GUI Settings

"action_name".defKeys
Description Specifies the list of the buttons displayed in the right key button frame
of dialog boxes. Each key name must be separated by a comma.

Value List of default keys that appear in each dialog box

Default Menu.defKeys = " "

InputArray.defKeys = "accept,inter-
rupt,insert,delete"

Displa- = "accept,interrupt"
yArray.defKeys

Input.defKeys = "accept,interrupt"

Construct.defKeys = "accept,interrupt"

Prompt.defKeys = "return"

Sleep.defKeys = "interrupt"

Getkey.defKeys = ""

Windows GUI Settings

This section describes the settings that affect the platform-specific appearance of the
user interface.

gui.mswindow.button
Description Specifies whether the buttons should look like Windows buttons or
like X11 buttons. For Windows clients only.

Value 0 Use X11 style buttons

1 Use Windows style buttons

Default 0

Syntax gui.mswindow.button=0

8-30 Four J’s Business Development Language User Guide

Local Editing Settings

gui.mswindow.scrollbar
Description Specifies if the scrollbars should look like Windows scrollbars or like
X11 scrollbars. For Windows clients only.

Value 0 Use X11 style

1 Use Windows style

Default 0

Syntax gui.mswindow.scrollbar=0

gui.user.font.choice
Description Restricts the end user from changing the fonts of the application with
the Windows front-end menu at runtime.

Value 0 The user is able to change the fonts

1 The user cannot change the fonts (except by changing the
local.tcl file)

Default 1

Syntax gui.user.font.choice=1

Local Editing Settings

The local editing feature reduces the communication between the server (where the
application is running) and the client (where the application appears). Enabling this
feature can reduce the network traffic and may speed up applications.

gui.local.edit
Description Enables or disables local editing.

Value 1 Enable local editing

The Four J’s Business Develpoment Language Configuration File 8-31

Cut, Copy, and Paste Feature Settings

0 Disable local editing

Default 1

Syntax gui.local.edit = 1

Cut, Copy, and Paste Feature Settings

The cut, copy, and paste feature allows you to cut or copy a selected string from one
field to another in a 4GL graphical application. To use this feature, the local editing
feature should be enabled.

To enable this feature, edit the fglprofile file. The local editing feature should be
enabled with:
gui.local.edit = 1

Then you can choose the short cut keys for cut, copy, and paste with:
gui.key.copy = "Control-c" (default value is Control-Insert)
gui.key.paste= "Control-v" (default value is Shift-Insert)
gui.key.cut= "Control-x" (default value is Delete)

Warning: If you want to redefine gui.key.copy as "Control-C", set

gui.key.interrupt to another value.

You can also define the message displayed when the user tries to use a local editing
feature in a not allowed field with:
gui.local.edit.error = "error string"

You can use the following keyboard equivalents:

• key Shift-Left: add character at the left to the selection
• key Shift-Right: add character at the right to the selection
• key Shift-Home: add from current character to first character to the selection
• key Shift-End: add from current character to last character to the selection

Example
The following code sample creates a 4GL application with two fields.

8-32 Four J’s Business Development Language User Guide

Cut, Copy, and Paste Feature Settings

File demo.per:
database formonly
screen {

[f01 ]

[f02 ]

}
attributes
f01=formonly.f01;
f02=formonly.f02;

File demo.4gl:
MAIN
DEFINE f01, f02 CHAR(20)
OPEN WINDOW w1 AT 1,1 WITH FORM "demo"
MENU "Cut&Paste"
COMMAND "Input"
INPUT BY NAME f01, f02
COMMAND "Exit"
EXIT MENU
END MENU
END MAIN

Then compile and run this program.

With the Windows client you can:

• Type text in the first field, select the text with the mouse or the shift key plus
any of the left, right, home, or end keys. Then copy or cut the string with the
assigned keys in the fglprofile. You can paste the string into the second field
or another Windows application.
• Type text in one of the fields, select a few characters in this field and type
new characters. The new characters replace the whole selected string.

With the X11 client, you can copy and paste between applications running the same
graphical daemon (that is, applications running with the same FGLSERVER value)
exactly the same as with the Windows client. However, to copy a string to another
X11 application (that is any Four J’s BDL application running with a different
FGLSERVER value), you have to perform the following steps:

• Select the string you want to copy with the mouse

• Select the 4GL application where you want to paste the string
• Press the Copy key

The Four J’s Business Develpoment Language Configuration File 8-33

Memory Mapping Settings

• Select the place where you want to paste the string and press the Paste key.

The reason for this is that X11 does not offer a Windows-type clipboard. Instead,
Four J’s BDL implements something similar to a Windows Clipboard for each appli-
cation running the same FGLSERVER value. When you paste a string into a 4GL
application, you need to put the string in the corresponding clipboard for the
application.

Memory Mapping Settings

Memory mapping allows the runtime system to load a single version of a P-code
application and share it across multiple connections, significantly reducing the
memory required on the application server.

The fglmkrun shell script output tells you if the runners have been built with or
without the memory mapping emulation.

Tip: Some systems do not support memory mapping. In this instance, an emulation
of this feature is provided. For Windows NT, an emulation is always used.

fglrun.mmapDisable
Description Enables or disables memory mapping.
Value 1 Disable memory mapping

0 Enable memory mapping

Default 1

Syntax fglrun.mmapDisable = 1

8-34 Four J’s Business Development Language User Guide

Chapter

The Debugger
9
In This Chapter . . . . . . . . . . . . . . . . . . . . 9-3
Requirements . . . . . . . . . . . . . . . . . . . . . 9-3
Installation . . . . . . . . . . . . . . . . . . . . . . 9-3
Starting the Debugger . . . . . . . . . . . . . . . . . . 9-4
Invoking debug mode on running applications . . . . . . . . . . . 9-4
UNIX platforms . . . . . . . . . . . . . . . . . . . 9-4
Microsoft Windows Platforms . . . . . . . . . . . . . . 9-5

Debugger Commands . . . . . . . . . . . . . . . . . . 9-5

9-2 Four J’s Business Development Language User Guide
In This Chapter
This chapter explains how to use the Four J’s BDL Debugger including:

• Requirements
• Installation
• Starting the debugger
• Invoking debug mode on running applications
• Debugger commands

Requirements
To run the Four J’s BDL Debugger requires a valid development or runtime licence.
A temporary or demo licence may not be used.

Installation
The Four J’s BDL Debugger is included in the Dynamic Virtual Machine (DVM). No
additional software is required to debug 4GL applications.

For more information on the installation of the compiler and the Dynamic Virtual
Machine see Chapter 2, “Installing Four J’s Business Development Language.”

Warning All 4GL programs must be recompiled to use the debugger

The Debugger 9-3

Starting the Debugger

Starting the Debugger

To use the debugger, start the DVM with the -d option
fglrun -d program

If a file extension is not specified, the DVM looks for a file called program.42r.

When debug mode is enabled, debug commands can be executed from the terminal
(UNIX) or command window (Windows NT/WIN2K).

A debug command file may be used to execute a set of commands. This command
file is specified with the -f option as in the following example:
fglrun -f cmdfile -d program

If a command file is not specified when using the -f option, the debugger will look
for, and use, a file with the same name as the executed 4GL program and an extension
of .4db

When the DVM is started with the -d option, a prompt for the entry of debugger
commands will be displayed at the command line.

To start the application, execute the “RUN” command on the debugger prompt.

To stop the debugger, execute the “EXIT” command.

Invoking debug mode on running applications

UNIX platforms
To activate debug mode on a 4GL application running on a Unix system, send the
TRAP signal to the DVM. To do this, ascertain the process number of the DVM and
send the TRAP command to the process - for example:

9-4 Four J’s Business Development Language User Guide

Microsoft Windows Platforms

On first terminal:
$ fglrun program.42r

On second terminal:
$ ps | grep fglrun
15966 pts/8 0:00 fglrun -d program.42r
$ kill -TRAP 15966

As this procedure requires that the process be attached to a terminal (for debugger
commands to be entered) it cannot be used if the DVM has been started in
background.

To stop the debugger, either leave the 4GL application or execute the “EXIT” debug
command.

Microsoft Windows Platforms

To activate debug mode on a 4GL application running on a Windows system, press
the CTRL+BREAK key combination in the command window where the runner was
started. For example:
c:\> fglrun program.42r

- open/select the command window

- press CTRL+BREAK

To stop the debugger, either leave the 4GL application or execute the “EXIT” debug
command.

Debugger Commands
An online help is provided within the debugger. To display the help, execute the
HELP command at the debugger prompt. You can specify the command name for
help on a particular command, for instance:
HELP RUN

The Debugger 9-5

Key commands

To obtain help for key commands, prefix the name of the command with an under-
score. Supported key names are _ESCAPE _INTERRUPT _REDRAW _SCREEN
and _TOGGLE

Key commands

_ESCAPE
The _ESCAPE command is used to send a command to the operating system. It is
invoked by using the ! (exclamation point) character.

Syntax !command

where command is an operating system command.

This feature can be used to invoke an interactive program, such as a text editor, that
requires keyboard input. When the command terminates, you are prompted to return
to the debugger. Pressing the [RETURN} key restores the command window and the
cursor returns to the window from which you escaped.

Note: Your system must have enough RAM to support the command entered while the
debugger is running.

Example:
!csh

will create a new UNIX C-shell. You can work at this shell and then return to the
debugger by using the UNIX “exit” command and pressing the {RETURN} key.

Related commands:

HELP

9-6 Four J’s Business Development Language User Guide

Key commands

_INTERRUPT
Pressing the _INTERRUPT key from an application screen will make the Command
window the current window. If the 4GL program is running, program execution is
suspended at the current 4GL statement.

The _INTERRUPT key setting depends on operating system and environment.

On Unix platforms, where FGLGUI is set to 0 (for text mode), the _INTERRUPT key
is that specified by the stty command (usually CTRL+C or DEL). On Unix platforms
where FGLGUI is set to 1 and for Windows platforms, the _INTERRUPT key is
CTRL+C by default but this value can be changed by the use of the fglprofile entry
gui.key.interrupt. For more information see “Key GUI Settings” on page 8-24
and“Interruption Signal” on page B-7

If the application screen is your current screen, pressing the _INTERRUPT key
restores the debugger screen and the command window becomes your current
window.

If a 4GL statement is executing, pressing the _INTERRUPT key stops execution

immediately after the statement has completed.

Note: Pressing the _INTERRUPT key stops execution of an application by inter-

rupting the Debugger process that interprets the program rather than by passing an
Interrupt signal to the 4GL program. To test how a 4GL application handles an
Interrupt signal, use the CONTINUE INTERRUPT command.

Warning: Pressing the _INTERRUPT key repeatedly while a 4GL program is

running can produce unpredictable results. For example, when the Application
screen is your current screen, consecutive interrupts may result in an incorrect
display of the Command window. If this happens, press CNTRL+R to redraw the
screen.

Related commands:

BREAK, CONTINUE, EXIT, REDRAW, HELP

_REDRAW
The _REDRAW key will redraw the Command window or the Application screen

The Debugger 9-7

Key commands

Syntax CTRL+R

On some terminals, sequences of Debugger commands can sometimes produce an

anomalous screen display - for example repeatedly pressing the _INTERRUPT key
when the Application screen prompts for input can produce strange results. If you
think that you Application screen or Command window is being incorrectly
displayed, press CTRL+R to redraw the current screen display.

If you are using a second terminal to display the output of the application program,
_REDRAW will redraw both screens.

Related commands:

APPLICATION DEVICE, HELP, _INTERRUPT, _SCREEN

_SCREEN

Syntax CTRL+P

Pressing CTRL+P will save the current display of the Application screen to a disk
file. This facility enables you to record the screens of a 4GL program. In combination
with other Debugger commands to display information, this can simplify the task of
documenting debugging sessions.

If the current window is the Application screen, pressing _SCREEN will save the
current screen display in a file called fglapscr. If this file already exists, the Debugger
will append the current display to the file.

If the APPLICATION DEVICE command has been used to designate a second

terminal for program output, it does not matter which is the current window - the
Debugger will update the fglapscr file with the current contents of the Application
screen.

Related commands:

APPLICATION DEVICE

9-8 Four J’s Business Development Language User Guide

Keyword commands

_TOGGLE
The _TOGGLE key will switch the screen display from the Debugger screen to the
Application screen and vice versa.

Syntax CTRL+T

Note:

Unless you use the _TOGGLE key or an APPLICATION DEVICE command, the
application screen will only appear when the 4GL program produces screen output or
requires keyboard input. The _TOGGLE command simply displays the application
screen, no input may be entered.

If the 4GL program does not produce an output screen, the _TOGGLE key has no
effect.
If the APPLCATION DEVICE command has been used to display output from the
4GL application, the _TOGGLE key has no effect.

Related commands:

APPLICATION DEVICE, _INTERRUPT, _SCREEN

Keyword commands

ALIAS
ALIAS assigns a name or function key to a command string.

The Debugger 9-9

Keyword commands

Syntax ALIAS { * | name = “cmd_str” | name = { “cmd_str” [; “cmd_str”... ] } }

ALIAS Required keyword

name An alias or the name of a function key

cmd_str specifies the command string

* Lists all of the current aliases.

On some terminal types a function key name , such as f1 for [F1], may be used as an
alias. Function key names must be defined in the file specified by the termcap
environment variable.

If terminal Setup keys have been used to program the function keys, the Debugger
may not recognize them.

The command string that is assigned to an alias can be the first part of a command or
it can group several commands enclosed by a single pair of braces ( {} ). Use a semi-
colon ( ; ) to separate commands.

The name specification may not be the complete name of another Debugger
command.

Entering the alias or pressing the function key will send the command string to the
Debugger. The Command window echoes the alias and then displays the expanded
command, substituting command strings for the alias, before executing the
command.

An alias persists until another ALIAS command reassigns the same name or
functions key or until an EXIT command ends the debugging session. If the
Programmer’s Environment is exited and debugging is resumed on the same 4GL
program without returning to the operating system the aliases are restored, otherwise
they are replaced by the initial default aliases.

9-10 Four J’s Business Development Language User Guide

Keyword commands

Examples:

If no aliases have been established, entering:

ALIAS *

displays the default aliases that are defined for the first nine function keys:
ALIAS f1 = HELP
ALIAS f2 = STEP
ALIAS f3 = STEP INTO
ALIAS f4 = CONTINUE
ALIAS f5 = RUN
ALIAS f6 = LIST BREAK TRACE
ALIAS f7 = LIST
ALIAS f8 = DUMP
ALIAS f9 = EXIT

To establish “x” as an alias for EXIT enter:

ALIAS x = EXIT

The next example assigns two commands to function key [F9]

ALIAS f9 = { PRINT ADD_FLAG; VIEW }

The command will now be executed by pressing the [F9] key or entering f9.

Related Commands

WRITE

APPLICATION DEVICE
APPLICATION DEVICE is used to redirect screen output from the 4GL application
to a second video terminal.

Syntax APPLICATION [DEVICE] device-name

The Debugger 9-11

Keyword commands

APPLICATION Required keyword

DEVICE Optional keyword

device-name The terminal device to display the application screen (required).

This must include the complete terminal pathname of the device.

This command enables continuous monitoring of the Application screen and can be
useful when working in a multi-user system with access to two terminals that can
support identical TERMCAP entries. The terminal specified in this command uses
the TERMCAP entry of the terminal that invoked the Debugger.

To find the terminal pathname of any logged in terminal, enter the command tty.

The second terminal is only used for output and its keyboard is not enabled until the
EXIT command is invoked from the terminal that is running the Debugger. If the
application program requires input, this must be entered from the keyboard of the
terminal that invoked the Debugger.

Both terminals MUST be logged in under the same account name.

Warning: If you invoke the APPLICATION DEVICE command you must specify a
different terminal to that which invoked the Debugger or you will have difficulty
reading screen output and the keyboard may lock up.

The _TOGGLE key has no effect after an APPLICATION DEVICE command.

The _INTERRUPT key will switch keyboard input to the command window if the
application requests input.

The following command selects a terminal designated as /dev/tty05 as the device to

display screen output from the application program being debugged
APPLICATION DEVICE /dev/tty05

Related commands:

EXIT, _INTERRUPT, LIST, WRITE

9-12 Four J’s Business Development Language User Guide

Keyword commands

BREAK
BREAK is used to set a breakpoint in program execution.

Syntax BREAK [*] [(function)] [“name”] [-count]

{ [[module.]line-no | variable | function | IF condition ] }

[{commands}]

BREAK required keyword

* symbol to disable the new breakpoint

(function) an optional function name enclosed in parentheses

“name” the name to give to the breakpoint

-count a negative signed integer. Execution stops when the breakpoint is

reached count times.

Default is 1.

module the module containing the breakpoint

line-no the line number within the module to set the breakpoint

variable the name of a variable that causes a break in program execution

whenever its value changes. Variable names may be qualified.

function the name of a function that causes a break in program execution when
the function is executed

IF an optional keyword specifying a condition

condition an expression that causes a break in program execution when the

expression is TRUE. The condition must reference a module (line-
no) or a variable or a function.

{commands} a list of commands within braces to be executed when the breakpoint

is reached

The Debugger 9-13

Keyword commands

A breakpoint will stop execution of the application immediately prior to executing

the program statement specified by the BREAK command.

The name option allows an optional name to be assigned to a breakpoint. The name
must start with a letter and it must appear in the command line within single or double
quotes.

If count is specified, it must be prefixed by a minus sign (-). Once a program reaches
an enabled breakpoint count times, execution stops whenever that breakpoint is
reached (that is the Debugger does not wait another count times before stopping but
stops every time thereafter). After a breakpoint is reached, CONTINUE or STEP can
be used to resume execution without resetting count. If RUN is invoked after a break-
point, the Debugger will reset count to its original value and execution will be
resumed.

If (function) is specified, the function name overrides the current function in deter-
mining the scope of reference of any variable in a variable specification. If the
module is omitted, line-no refers to the current module. When (function) is specified,
execution stops whenever the function is entered.

The scope of reference of any variable in the commands list is determined by its
qualifiers and by the function that is current when the breakpoint takes effect. The
Debugger disregards whatever function was current when the BREAK command was
issued and ignores the (function) option in identifying the scope of any variables in
commands.

If line-no is not an executable statement, the Debugger places the breakpoint at the
start of the next executable program statement or at the last statement in the function
whichever is first. Variable definition statements, blank lines and comments are not
executable statements. If the module contains no executable statements an error
message is displayed. If line-no is not the first line of a program statement, the break-
point stops execution at the first line of the program statement.

When both (function) and count are specified, the breakpoint is reached count times
before execution stops at the function entry point.

The line number of a 4GL statement that calls a C or 4GL library function may be
specified but a function that is not itself a programmer-defined 4GL function may
not.

If both a count and an IF condition are specified, the count is only reduced if the
condition is TRUE.

9-14 Four J’s Business Development Language User Guide

Keyword commands

If several BREAK IF commands reference variables, the Debugger suspends

execution if any of the variables change when one of the breakpoint conditions is
true. It may be necessary to specify DISABLE commands in the command list to
avoid unplanned breaks in the situation.

Tip: There is no limit to the number of breakpoints that can be set at any one time but
if many breakpoints are simultaneously active it can be helpful to include a
distinctive PRINT message as a command option to identify which breakpoint
stopped execution.

The Debugger assigns a unique reference number to each breakpoint. When a new
breakpoint is established, its reference and number is displayed at the Command
window along with other specifications, such as name, line number, function,
module, commands to execute and scope, depending on the arguments of the
BREAK command.

Setting a breakpoint with the BREAK command also enables the breakpoint unless
the asterisk (*) symbol is included. The asterisk symbol is used to create a breakpoint
without enabling it - the breakpoint is specified but disabled as if it had been set and
then been deactivated using the DISABLE command.

Examples:
BREAK 10

This command will set an unnamed breakpoint at the tenth line of the current module.
When the breakpoint is reached the Command window will display its reference
number, the word BREAK, the function, line number, module and scope of reference.
BREAK main.100

This command will set a breakpoint at line 100 in module main.

BREAK x

The Debugger 9-15

Keyword commands

The Debugger will first search for a function named x. If x is a function within the
current program, this breakpoint will suspend execution after a statement that calls x.
If no function named x is found, the Debugger will search for a variable named x. If
found, the Command window displays the reference number of the new breakpoint,
the word BREAK and the name of the variable. The next line will display its scope
of reference. Program execution will stop when the value of x changes. If both a
function and a variable have the name x and the variable is required, the variable must
be prefixed with appropriate qualifiers in the BREAK command.

If neither a function nor a variable is found named x, the Command window displays
the error message:
-16351: Variable [x] could not be located

BREAK x[i]

When the above command is entered, the Debugger will immediately evaluate array
member x[i] and return an error if i does not contain a value.
BREAK global.flag

The above command causes a breakpoint when the value of global variable flag
changes.
BREAK “x” -2 20 if global.flag = 3 {print “Flag=3”}

The above statement sets a breakpoint at line 20 in the current module. The break-
point causes execution to stop if the breakpoint is reached twice and the global
variable “flag” is equal to 3 each time. When execution stops, the PRINT statement
is executed.

Related commands:

DISABLE, ENABLE, LIST, NOBREAK, STEP, WRITE

CALL
The CALL function is used to execute a function and display returned values.

9-16 Four J’s Business Development Language User Guide

Keyword commands

Syntax CALL function ([arg [,...]])

CALL Required keyword

function the name of the function to execute

arg an argument of the function

The called function may be a programmer-defined 4GL function, a 4GL library

function, a C function or an -INFORMIX-ESQL/C- function. The function does not
have to be part of a completed 4GL program with a main program block and it may
contain breakpoints and tracepoints.

The function name must be followed by left and right parentheses even if the function
has no arguments. Multiple arguments must be separated by a comma (,) and any
4GL program variables that are specified as arguments must be active.

Any output from the function is displayed on the Application screen, returned values
are displayed in the Command window.

A function may be CALLed before a RUN command has started program execution
but if it includes SQL statements referencing a database which is not the current
database, the database must be specified before the function is CALLed. The
database may be specified by a DATABASE command or by a RUN command to
start the current program if that program includes an appropriate DATABASE
statement.

It may be necessary to use the CLEANUP command to reinitialize variables and

close forms and windows before re-executing a function by repeating a CALL
command.

Examples:
CALL main()
CALL find_cust (50,0)
CALL err_get (-408)

The first example will execute the main section of the current program.

The Debugger 9-17

Keyword commands

The second command will execute a function names “find_cust” with arguments of
50 and 0.

The third command will execute a built-in 4GL function and display the 4GL error
message -408 in the command window.

Related commands:

CLEANUP, DATABASE, FUNCTIONS, RUN, STEP, TRACE, VARIABLE,

WHERE

CLEANUP
The CLEANUP command initializes all variables, closes all open windows and
forms and, optionally, closes the current database.

Syntax CLEANUP [ALL]

CLEANUP Required keyword

ALL optional keyword specifying that the current database should be

closed.

The CLEANUP command can be helpful when a function executed with the CALL
command has not reached a normal termination but it is necessary to CALL it again.
In some debugging situations this command is necessary before a CALL command
can be executed to restart a function that terminated abnormally.

It is unnecessary to invoke the CLEANUP command before a RUN command as

invoking RUN automatically initializes all program variables and closes all forms
and windows before execution starts.

After a CLEANUP command, a RUN or CALL command must be issued before the
CONTINUE or STEP commands are used.

Related commands:

CALL, DATABASE, EXIT, LET, RUN

9-18 Four J’s Business Development Language User Guide

Keyword commands

The Debugger 9-19

Keyword commands

CONTINUE
The CONTINUE command is used to resume execution of a program or to send an
Interrupt or Quit signal to a currently running 4GL program.

Syntax CONTINUE [INTERRUPT | QUIT]

CONTINUE required keyword

INTERRUPT optional keyword that passes an Interrupt to the 4GL program

QUIT optional keyword that passes a Quit signal to the 4GL program

A CONTINUE without any options resumes execution at the first 4GL statement
after an interrupt or breakpoint. If execution has not begun, or has terminated, or if
CLEANUP followed the last RUN or CALL command, an error message will be
displayed at the Command window.

The Debugger traps all Interrupt signals. The INTERRUPT and QUIT options send
an INTERRUPT or QUIT signal to the program to test signal handling code. Whether
or not the INTERRUPT or QUIT option interrupts or terminates program execution
depends on how the program handles these signals. On systems that cannot generate
a Quit signal, the QUIT option has no effect.

If the INTERRUPT or QUIT option terminates program execution, the Command

window displays the name of the module, function and line number of the current
4GL statement when execution ceased. Neither STEP not CONTINUE can resume
execution but DUMP, PRINT and WHERE are available for examination of active
variables and functions.
For information about setting interrupt characters see: “_INTERRUPT” on page 7.

Related commands:

BREAK, CALL, CLEANUP, INTERRUPT, STEP, RUN

9-20 Four J’s Business Development Language User Guide

Keyword commands

DATABASE
The DATABASE command is used to specify the required current database.

Syntax DATABASE database-name

DATABASE required keyword

database-name the name of an existing database

If no database has been selected, a DATABASE command selects and opens one. If
a database has been selected and is correct, DATABASE closes it and replaces it with
database-name.

Invoking the RUN command reopens the database specified in the 4GL program. To
use a different database, set a breakpoint at the first line in the main program block
and invoke the DATABASE command to select a new database when that breakpoint
is encountered. CONTINUE may then be used to continue execution.

The following example shows a sequence of commands that set a breakpoint at the
beginning of main, begins running the program, selects a new database called
“stereos” and resumes program execution using the new database.
BREAK main
RUN 9 5
DATABASE stereos
CONTINUE

Related commands:

CALL, CLEANUP, RUN

The Debugger 9-21

Keyword commands

DISABLE
The DISABLE command is used to turn off a breakpoint or tracepoint.

Syntax DISABLE {name | refno | function | ALL}

DISABLE required keyword

name the programmer-assigned name of a breakpoint or tracepoint

refno the Debugger-assigned reference number of a breakpoint or

tracepoint

function the name of a function

ALL optional keyword

The ALL option disables all breakpoints and tracepoints within the current 4GL
program.

The function option disables all breakpoints and tracepoints within the specified
function.

If a breakpoint or tracepoint is enabled and has the same name as a function, only the
breakpoint or tracepoint called name is disabled. If that breakpoint or tracepoint is
already disabled, all breakpoints and tracepoints within the function called name are
disabled.

The breakpoint or tracepoint name may be optionally enclosed in single or double

quotes.
DISABLE does not remove breakpoints or tracepoints and they can be reactivated at
a later time by invoking the ENABLE command.
If a breakpoint or tracepoint named ALL is enabled, the DISABLE ALL command
will disable that breakpoint or tracepoint only, rather than disabling all of them.

9-22 Four J’s Business Development Language User Guide

Keyword commands

DUMP
The DUMP command will write the names and values of variables in the current
function to the Command window or an ASCII file.

Syntax DUMP [GLOBALS | ALL] [>> filename]

DUMP required keyword

GLOBALS optional keyword to specify global variables only

ALL optional keyword to specify both function and global variables

>> symbols used to send output to disk

filename the name of the required output file

The current function as used by this command is the most recently executed function.
After a fatal error or other action causes a 4GL program to terminate abnormally,
DUMP will evaluate the variables from the function where execution ceased.

If neither GLOBALS nor ALL is specified, only the variables in the current function
are evaluated. If GLOBALS is specified, only the global variables are evaluated.

If a file called filename already exists, the Debugger will append the names and
values to that file. If the file does not exist, the Debugger will create it. By default,
the file will be created in the current directory. If the file is to be created outside the
current directory, the full path must be specified.

An error message is displayed if no 4GL function is active. DUMP may not be used
to evaluate variables that exist only in C or -INFORMIX-ESQL/C- functions.

Related commands:

LET, TRACE, VARIABLE

ENABLE
The ENABLE command is used to activate a breakpoint or tracepoint.

The Debugger 9-23

Keyword commands

Syntax ENABLE {name | refno | function | ALL }

ENABLE Required keyword

name the programmer assigned name of the breakpoint or tracepoint

refno The Debugger assigned reference number of the breakpoint or

tracepoint

function the name of a function

ALL Optional keyword

The ALL option enables all breakpoints and tracepoints within the current 4GL
program.

The function option enables all breakpoints and tracepoints within the specified
function.

If a breakpoint or tracepoint is enabled and has the same name as a function, only the
breakpoint or tracepoint called name is enabled. If that breakpoint or tracepoint is
already enabled, all breakpoints and tracepoints within the function called name are
enabled.

The breakpoint or tracepoint name may be optionally enclosed in single or double

quotes.

If a breakpoint or tracepoint named ALL is enabled, the ENABLE ALL command will
enable that breakpoint or tracepoint only, rather than enabling all of them.

Related commands:

BREAK, DISABLE, LIST, NOBREAK, NOTRACE, TRACE, WRITE

EXIT
The EXIT command is used to terminate a debugging session.

9-24 Four J’s Business Development Language User Guide

Keyword commands

Syntax EXIT

EXIT required keyword

If the debugger was invoked directly from the system prompt, EXIT will return
control to that prompt. If the debugger was invoked from the Programmer’s
Environment, enter EXIT and press [RETURN] to return to a menu.

If you are at the Application screen with program waiting for input or producing
output, the _INTERRUPT key must first be pressed before it is possible to EXIT.

Related commands:

_INTERRUPT

FUNCTIONS
The FUNCTIONS command is used to list all programmer-defined functions in the
current application.

Syntax FUNCTIONS [pattern] [>> filename]

FUNCTIONS Required keyword

pattern an optional search pattern specification expressed as a string of one

or more characters

>> symbols used to redirect output to a disk

filename an optional output file

Where no search patterns follow the FUNCTIONS keyword, the names of all
functions within the current application are displayed in the Command window.

The search pattern specification may include a function name or any combination of
characters, blanks and the following special characters:

The Debugger 9-25

Keyword commands

? Match any non-blank character

* Match zero or more non-blank characters
[d-q] Match any character between d and q inclusive in the ASCII collating
sequence.

If a search pattern is specified, FUNCTIONS will display every function that matches
the pattern. If no function names match the pattern, the Command window returns to
the $ prompt and no additional message appears.

FUNCTIONS will not list the names of -INFORMIX-ESQL/C- or C functions.

Examples:
FUNCTIONS

This will return the names of all programmer-defined functions in the current
application
FUNCTIONS add_cust

This will search the source files for a function called add_cust. If the function is
found, its name is displayed in the command window.
FUNCTIONS add*

This specifies a “wildcard” pattern that will match the previous example as well as
any other function that starts with “add”.
FUNCTIONS *ust[n-w]*

This command will list the names of all functions whose names contain the pattern
“ust” followed by any lower case letter from n to w inclusive.

Related commands:

CALL, TRACE, VIEW, WHERE

HELP
The HELP command is used to find instructions for using Debugger commands.

9-26 Four J’s Business Development Language User Guide

Keyword commands

Syntax HELP [command]

HELP Required keyword

command an optional Debugger command

If no command argument is specified, a brief synopsis of every Debugger command

is displayed in the Debugger window. The same synopsis is displayed if a string that
begins with an alphabetic character is entered after the keyword HELP that does not
correspond to a keyword. If the HELP argument begins with any other non-alpha-
betic character, an error message and the synopsis of every Debugger command is
displayed.

As well as the debugger command keywords, the HELP command recognizes the
five key commands _ESCAPE, _INTERRUPT, _SCREEN, _REDRAW and
_TOGGLE which represent the Debugger commands controlled by special non-
alphabetic characters. Each of these key commands must be prefixed by the under-
score (_) character.

The HELP command may be abbreviated to H.

LET
The LET command is used to assign an expression to a variable

Syntax LET variable = expression

LET required keyword

variable the name of a program variable

expression the expression to be assigned to the variable

The Debugger 9-27

Keyword commands

Should a 4GL program assign to a variable a value which is different to that intended,
the LET command will allow the substitution of the correct value so that the
debugging session may be continued without modifying and recompiling the
program. It should be noted, however, that the LET command has no effect on the
source code - this will have to be corrected after the debugging session is complete.

The value that a LET statement assigns to a variable should be consistent with the
data type declaration of that variable. If the two are different, the Debugger attempts
to convert the value which may result in truncation. If the conversion fails an error
message is displayed.

The syntax of the LET command closely resembles that of the 4GL LET statement.
An expression can be qualified, contain a substring of a character array but cannot
include function calls, variables from multiple functions or variables from functions
not currently active. Character expressions must be enclosed in quotation marks.

LET cannot be used to reference variables unless program execution is suspended or

has terminated abnormally after a RUN or CALL command.

If a LET command is followed by a RUN command, the RUN command will reini-
tialize all the program variables, restoring their initial values. To avoid the LET
command being undone in this way, set a breakpoint before a 4GL statement that
uses a variable whose value is incorrect and issue the LET command when the break-
point halts execution. Invoke the CONTINUE command to resume execution with the
corrected value.

9-28 Four J’s Business Development Language User Guide

Keyword commands

Examples:
LET answer = “y”

will assign the character ‘y’ to the variable called ‘answer’.

LET global.rfrsh_flg = function.main.x/23

The above statement will divide the variable called x, which was defined in the main
program block, by 23 and assign the resulting value to the global variable rfrsh_flg.
If the data type of global.rfrsh_flg is INTEGER, the decimal portion of the value is
discarded.
LET x[101,101] = y

The above statement replaces the current value of the 101st character of variable ‘x’
with the value of the variable ‘y’.

Related Commands:

DUMP, PRINT, RUN, TRACE, VARIABLE

LIST
The LIST command is used to display the current breakpoints and tracepoints.

Syntax LIST [BREAK | TRACE]

LIST Required keyword

BREAK optional keyword to specify the listing of current breakpoints

TRACE optional keyword to specify the listing of current tracepoints

If BREAK is specified, the reference numbers and other specifications of the

currently enabled and disabled breakpoints are displayed at the Command window.

If TRACE is specified, the reference numbers and other specifications of the

currently enabled and disabled tracepoints are displayed at the Command window.

If neither option is specified, information about both breakpoints and tracepoints is

displayed.

The Debugger 9-29

Keyword commands

NOBREAK
The NOBREAK command is used to remove (rather than simply disable) a
breakpoint.

Syntax NOBREAK { name | refno | function | ALL }

NOBREAK required keyword

name the programmer-assigned name for a breakpoint

refno the debugger-assigned reference number for a breakpoint

function the name of a program function

ALL an optional keyword to designate all breakpoints

NOBREAK should be used to delete a breakpoint. To deactivate a breakpoint that

may be reactivated at a later stage, use the DISABLE command.

The LIST BREAK command displays the current reference numbers and names that
may be used for the refno and name options of the NOBREAK command.

The ALL option removes all breakpoints in the program unless a breakpoint called
ALL exists, in this case only that breakpoint will be deleted rather than all of them.

If a function is specified, the Debugger will remove all breakpoints within that
function except where a function and a breakpoint have the same name. In that case
only the named breakpoint will be removed. To remove ambiguity, a breakpoint
name may be enclosed in single or double quotes.

For example:
NOBREAK fnbr

If this command is entered, the Debugger will first look for a breakpoint called
“fnbr”. If it exists it will be removed, if it does not the Debugger will look for a
function named “fnbr” and remove all the breakpoints within that function.
NOBREAK “fnbr”

This command will only look for, and remove, a breakpoint named “fnbr”.
NOBREAK 4

9-30 Four J’s Business Development Language User Guide

Keyword commands

The above command will remove the breakpoint with a reference number of 4.

Related commands:

BREAK, DISABLE, ENABLE, LIST, STEP, WRITE

NOTRACE
The NOTRACE command is used to remove (rather than simply disable) a
tracepoint.

Syntax NOTRACE { name | refno | function | ALL }

NOTRACE Required keyword

name the programmer-assigned name for a tracepoint

refno the debugger-assigned reference number for a tracepoint

function the name of a program function

ALL an optional keyword to designate all tracepoints

NOTRACE should be used to delete a tracepoint. To deactivate a tracepoint that may

be reactivated at a later stage, use the DISABLE command.

The LIST TRACE command displays the current reference numbers and names that
may be used for the refno and name options of the NOTRACE command.

The ALL option removes all tracepoints in the program unless a tracepoint called
ALL exists, in this case only that tracepoint will be deleted rather than all of them.
If a function is specified, the Debugger will remove all tracepoints within that
function except where a function and a tracepoint have the same name. In that case
only the named tracepoint will be removed. To remove ambiguity, a tracepoint name
may be enclosed in single or double quotes.

The Debugger 9-31

Keyword commands

For example:
NOTRACE fnbr

If this command is entered, the Debugger will first look for a tracepoint called “fnbr”.
If it exists it will be removed, if it does not the Debugger will look for a function
named “fnbr” and remove all the tracepoints within that function.
NOTRACE “fnbr”

This command will only look for a tracepoint named “fnbr”.

NOBREAK 4

The above command will remove the tracepoint with a reference number of 4.

Related commands:

TRACE, DISABLE, ENABLE, LIST, STEP, WRITE

PRINT
The PRINT command is used to display the value of an expression or to save it to a
file or to pass it to an external program.

Syntax PRINT expression [{ >> filename | PROGRAM = progname }]

PRINT required keyword

expression the expression to be evaluated

>> symbols used to redirect output to a disk

filename the name of the optional output file

PROGRAM optional keyword to indicate that a BLOB variable is to be passed as

an argument to an external program

progname the name of the external program to which the BLOB variable is
being passed

9-32 Four J’s Business Development Language User Guide

Keyword commands

An expression can be the name of a variable, a record, an array or a substring of a

character array. It can be a quoted string or an arithmetic expression but may not
contain a function call. The expression may not include non-global variables from
multiple functions or from a function that is not active and it may not reference any
program variables unless a CALL or RUN command has started program execution.

Variable names in an expression may be qualified. If a non-global variable is defined

in another active function that is not the current function, the variable must be
qualified to be referenced in a PRINT statement.

PRINT can be used to display the current values of an entire record or array by speci-
fying its name as the expression. PRINT can also be used like a calculator during
debugger sessions to perform arithmetic operations.

The PROGRAM option can only be used when printing BLOB variables. The
debugger first copies the BLOB to a temporary work area and then calls progname
with the work file name as an argument.

Filename may include a full path if values are to be saved to a file outside the current
directory. If output is redirected to a file that already exists, the Debugger will append
the output to that file, otherwise the file is created. If no filename is specified, the
returned vales are displayed in the Command window,

Examples:
PRINT x

the above command will display the value of variable called x. This can be a simple
variable or a record or an array.
PRINT 365/7

the above command will divide 365 by 7 and display the result in the Command
Window.
PRINT SQLCA

the above command will display an entire SQLCA record on the screen.
PRINT global.sqlca.sqlcode >> glbstatus

the above command will copy, to a disk file called glbstatus, the current value of
sqlcode.
PRINT wrtschz[1,20]

The Debugger 9-33

Keyword commands

the above command will display the first 20 characters of the CHARACTER variable
wrtschz.
PRINT blobvar PROGRAM = “vi”

the above command will copy the contents of the BLOB variable blobvar to a
temporary file and then call the vi editor with the temporary filename as an argument.
The vi commands may then be used to view the entire BLOB value.

Related Commands:

CALL, DUMP, LET, RUN, TRACE, VARIABLE

READ
The READ command is used to execute Debugger commands from a file

Syntax READ filename[.4db]

READ required keyword

filename the name of a .4db command file

The READ command enables the execution of Debugger commands that are
specified in an ASCII file. These commands are executed and their output displayed
at the Command window.

Tip: If you use the WRITE command to save features of a debugging session, you can
use a subsequent READ command to reestablish those features.

The required extension of filename is .4db although this need not be specified in the
READ command. The command file may created with an editor or with a WRITE
statement and subsequently modified with an editor. If the .4db command file is
outside the current directory, the full path must be supplied.

READ commands may be included in a .4db command file but an error message will
be generated if there are more than 10 levels of nested READ commands or if an
attempt is made to READ a file that is currently being processed by another READ
command.

9-34 Four J’s Business Development Language User Guide

Keyword commands

READ cannot be used to execute the following commands or control characters that
are not based on keywords:

Command Function

Escape (!) Operating system commands

Interrupt Switches control to the Command window

CONTROL-P Saves the screen display as a file

CONTROL-Q Enables terminal I/O

CONTROL-R Redraws the screen display

CONTROL-S Suspends terminal I/O

CONTROL-T Toggles Application screen

Related Commands:

WRITE

RUN
The RUN command is used to start or restart execution of an application during a
debugging session.

Syntax RUN [arg [arg...]]

RUN required keyword

arg an argument to the application

If multiple arguments are used they should be separated by spaces.

If RUN is executed more than once during a debugging session, the same arguments
are reused. The arguments may be changed by specifying new ones in the RUN
command.

The Debugger 9-35

Keyword commands

Before RUN restarts an application, it first performs the functions of a CLEANUP

command, closing the database and any open forms or windows and then initializing
all program variables. Run will also reinitialize the COUNT specification of an
enabled breakpoint to its initial value. To maintain current values use the
CONTINUE or STEP command.

RUN may not be included in the commands list of a TRACEPOINT.

Related Commands:

BREAK, CALL, CONTINUE, INTERRUPT, STEP

STEP
The STEP command is used to execute one or more individual program statements.

Syntax STEP [n] [INTO] [NOBREAK]

STEP required keyword

n the number of steps to execute. Default = 1

INTO optional keyword to continue execution of the steps into a function

NOBREAK optional keyword to continue steps regardless of breakpoints

Each step is a single executable program statement - variable definition statements,

blank lines and comments are not executable statements.
A function call is treated as a single statement unless the INTO option is specified.
When INTO is specified, each executable statement within the function is treated as
one step. The INTO option may not be used with C functions or 4GL library
functions.

If, while processing a STEP command, an enabled breakpoint is encountered,

execution will stop unless the NOBREAK option has been specified. If neither INTO
nor NOBREAK has been specified, execution stops if a step reaches a function that
contains an enabled breakpoint.

9-36 Four J’s Business Development Language User Guide

Keyword commands

When NOBREAK is specified, breakpoints have no effect while the STEP command
is executing. The breakpoints are not removed or disabled, simply ignored for the
duration of the STEP command.

Before the STEP command can be invoked, program execution must be initiated with
the CALL or RUN command and then suspended with a breakpoint or interrupt
command. An error message will be displayed if program execution terminates or a
CLEANUP command is encountered while a STEP command is being processed.

Examples:
STEP

The above command will execute the next line as one statement even if it includes a
function call.
STEP 12

The above command will execute the next 12 statements, not counting the statements
within a function call as steps. Execution will stop at an enabled breakpoint or at the
call of a function that contains an enabled breakpoint.
STEP 10 INTO

The above statement will execute the next 10 program statements. If a function call
is encountered, executable statements within the function are counted as individual
steps. If an enabled breakpoint is encountered before the 10 statements are executed,
execution will stop at that breakpoint.
STEP 5 INTO NOBREAK

The above command will execute the next 5 statements, counting statements within
functions as steps. If a breakpoint is encountered it will be ignored and execution will
not stop.

The Debugger 9-37

Keyword commands

Including or not including the INTO or NOBREAK options will produce very
different results when STEPping though a program that calls a function containing a
breakpoint. With the following source code as an example, assume there is an
enabled breakpoint at line 8 and program execution is currently suspended at line 2:
1 MAIN
2 CALL a()
3 END MAIN
4
5 FUNCTION a()
6 DEFINE i INTEGER
7 LET i = 7
8 DISPLAY i
9 DISPLAY “DONE”
10 END FUNCTION

For this example, the following STEP commands respectively stop executing at the
line listed on the right:

STEPCommand Stops at line

STEP 8
STEP INTO 7
STEP NOBREAK 3
STEP INTO NOBREAK 7
STEP 3 8
STEP 3 INTO 8
STEP 3 INTO NOBREAK 9

Related commands:

BREAK, CALL, CONTINUE, ENABLE, DISABLE, FUNCTIONS, NOBREAK,

RUN, TRACE

TRACE
TRACE is used to show when a statement or function executes, of when the value of
a program variable changes.

9-38 Four J’s Business Development Language User Guide

Keyword commands

Syntax TRACE [ * ] [ (function) ] [“name”] { [module.]line-no | variable |

function | FUNCTIONS } [{commands}] [>> filename ]

TRACE required keyword

* an optional symbol to disable the tracepoint

(function) an optional function name, in parentheses

name an optional identifier for the tracepoint

module the name of the module containing the line to be traced

line-no the line number (within the module) that will be displayed when it
executes

variable the name of the variable that will be displayed when its value changes

function the name of the function to display when its execution begins and
when it returns

FUNCTIONS an optional keyword that specifies tracing execution of all functions

{commands} a list of Debugger commands in braces ( {} ) to be executed when the

tracepoint in encountered

>> symbols used to redirect output to a disk

filename the name of an output file to receive the tracepoint display

The Debugger assigns a unique reference number to each tracepoint and when a
TRACE is executed, the reference number and other specifications of the tracepoint
are displayed at the Command window. These specifications can include its name,
line number, function, module, output file, commands to execute and scope. There is
no restriction on the number of tracepoints that can be set at any time.

Setting a tracepoint with the TRACE command also enables it, unless the asterisk (*)
symbol is included. If the asterisk is specified, the tracepoint is defined but disabled,
as if it had been set and a DISABLE command issued.

The Debugger 9-39

Keyword commands

If a name for the tracepoint is specified, it must be enclosed in single or double

quotes, start with a letter (although subsequent characters may be letters, numbers or
the underscore (_) symbol) and it must not duplicate the name of another breakpoint
or tracepoint.

If the module name is omitted, line-no refers to the current module.

If line-no is not an executable statement, the tracepoint is set at the next executable
statement following line-no.

When a tracepoint is set on a variable, the variable name and its contents are
displayed at the Command window every time the value of the variable changes.
When a tracepoint is set on a function, the function name and parameters are
displayed when the function is entered and the function name and returned values are
displayed when execution of the function is complete. Any function that the current
program calls may be specified including C functions, SQL functions and library
functions. If commands are specified while tracing a function, the commands are
only executed when the function is entered. The commands list must be enclosed
within braces ({}) and semi-colons (;) are used to separate commands. A commands
list may not include a CALL, CONTINUE, STEP or RUN command.
The scope of reference of any variables in the commands list is determined by their
qualifiers and by any function that is current when the tracepoint takes effect. The
Debugger disregards whatever function was current when the TRACE command was
issued and also ignores the (function) option in identifying the scope of any variable
in a command. Variables may be optionally qualified.

Examples:
TRACE 15

The above command establishes a tracepoint with no name at line 15 of the current
module. The reference number, module and scope of reference of the tracepoint is
displayed at the Command window:
TRACE main:15 [r_main.4gl]
scope function: main

TRACE x

9-40 Four J’s Business Development Language User Guide

Keyword commands

When the above command is entered, the Debugger will search for a function of the
current program called x. If function x is found, the display at the Command window
will show its name and parameters when the function is entered and its name and
returned values after the function returns. If no function called x is found, the
Debugger searches for a variable called x, applying the scope of reference rules. If
variable x is found, its name and value are displayed at the Command window
whenever its value changes.

If both a function and a variable have the name x, the variable must be prefixed with
appropriate qualifiers in a TRACE command to set a tracepoint on the variable.

If neither a function nor a variable named x is found, the error message:

-16351: Variable [x] could not be located

is displayed at the Command window.

TRACE GLOBAL.SQLCA.SQLCODE

The above command displays the name and value of the internal variable SQLCODE
whenever it changes. As SQLCODE is set to zero after each successfully executed
SQL statement, this tracepoint will identify queries that return no rows and unsuc-
cessfully executed statements.
TRACE * “vestige” CMENU.12 {VA ALL} >> vestigial

The above command specifies (but does not enable) a tracepoint called “vestige” at
the 12th line of the module called CMENU. If this tracepoint is later enabled and the
statement on this line is executed, the Debugger executes a VARIABLE ALL
command when the tracepoint is reached and saves the output to a file called
vestigial.
TRACE (funca) reca.b

The above command sets a tracepoint on member b of the record named reca in
function funca. The Debugger will display the name and value of reca.b whenever it
changes but will ignore any variable called reca.b in any other function. The
(function) specification requires fewer keystrokes than using qualifiers, as in the
equivalent command:
TRACE function.funca.reca.b

Related commands:
DISABLE, ENABLE, LIST, NOTRACE, WRITE

The Debugger 9-41

Keyword commands

USE
USE is used to specify or display the source file search path

Syntax USE [ [=] pathname [, ...]]

USE required keyword

pathname a full or relative pathname

= an optional symbol to replace the current search path with a new path

Entering the USE command without any arguments will display the current directory
search path at the Command window.

If any source files are in directories outside the current search path, the USE
command enables the addition of other directories. If multiple directories are listed
in the USE command, directories will be search in the order they were specified.

If the equal sign (=) is included in the USE command, the new pathname(s) replace
the current search path, if the equal sign is omitted , the pathname(s) take precedence
in the search order, ahead of the following directories:

• directories from previous USE commands

• the current directory
• the directory associated with the application.

The modified search directory order established by the USE command persists for the
duration of the current debugging session or until the next USE command.

During a debugging session, exiting to the Programmers environment and then

resuming the debugging of the same application without returning to the operating
system will not clear down the source file path.

Related commands:

WRITE

9-42 Four J’s Business Development Language User Guide

Keyword commands

VARIABLE
The VARIABLE command is used to display the declaration of a variable, including
the scope of reference and data type specification, or to save it in a file.

Syntax VARIABLE [variable | GLOBALS | ALL] [>> filename]

VARIABLE required keyword

variable the name of a program variable

GLOBALS optional keyword to ignore local variables

ALL optional keyword to include all variables

>> symbol to redirect the output to a file

filename filename where output is to be redirected

If none of variable, GLOBALS or ALL is specified, the type of each variable in the
current function is displayed but global variables outside the current function are
ignored. If GLOBALS is specified, only the types of the global variables are
returned. If ALL is specified, the Debugger returns the data types of all global
variables in the application and all the local variables in the current function.

If variable is a record, the name and data type of each component variable are
displayed.

The scope of reference of a variable may be qualified by prefixing the variable with
a qualifier. Possible qualifiers include:

Qualifier Scope

GLOBAL. in all modules

MODULE.mod-name. in the specified module

FUNCTION.func-name. in the specified function

rec-name[.rec-name ...]. in the record [within another record ...]

The Debugger 9-43

Keyword commands

The VARIABLE command can only return the declarations of variables in program
functions. If a C or SQL function is the current function, only the ALL or GLOBALS
options return data type information. Both options declare the global variables but no
local variables.

If an output file is specified, the display is redirected to that file. If the file already
exists, output is appended to it.

Examples:
VARIABLE FUNCTION.add_order.num_cust

The above function will display the declaration of the variable num_cost in a function
called add_ord.
VARIABLE ALL >> snapshot

The above function will save the declarations of all global variables in the program
plus any other variables of the current function to a file in the current directory called
“snapshot”. This output is not displayed at the command window.

Related Commands:

DUMP, LET, PRINT

VIEW
VIEW is used to display a specific 4GL function or module in the Command window.

Syntax VIEW [line-no | module | function]

VIEW required keyword

line-no the line number within the module

module the name of the module to be displayed

function the name of the function to be displayed

9-44 Four J’s Business Development Language User Guide

Keyword commands

If the VIEW command is entered without additional options, the first ten lines of the
source code for the current module are displayed at the Command window. Subse-
quent VIEW commands will display the next ten lines in sequence and so on. If a line
number is specified, lines (line-no -5) to (line-no +4) are displayed.

If a module and function have the same name, the function is displayed.

The VIEW command cannot display a C function, a 4GL library function or an SQL
function.

Related commands:

CALL, FUNCTIONS, INTERRUPT

WHERE
The WHERE command is used to display the name and argument of each 4GL
function that was called to reach the current 4GL statement, or to redirect this infor-
mation to a file.

Syntax WHERE [>> filename]

WHERE required keyword

>> Symbols used to redirect output to a disk

filename the name of the optional output file

The WHERE command will display a list of functions that have been called before
the current 4GL statement has executed, but have not yet returned. The line and
source module from where the function call was made is also displayed along with
any parameters that were passed to it.

The WHERE command will normally only describe programmer-defined 4GL

functions. An exception to this is when a WHERE statement appears in the command
list of a tracepoint that has been set on a C or SQL function. In this case, when the
tracepoint is reached, the WHERE statement evaluates any parameters that were
passed and lists the C or 4GL library function, as opposed to the module and line
number of the calling statement, and lists active functions.

The Debugger 9-45

Keyword commands

WHERE can be used when execution is suspended or after a function or program

terminates abnormally. If no 4GL program is currently executing an error message is
displayed:
-16387 Program is not currently being executed

Related commands:

CALL, CLEANUP, FUNCTIONS, RUN, TRACE

WRITE
The WRITE command is used to save in a file the commands to establish break-
points, tracepoints, aliases, directory search path specifications and terminal display
parameters.

Syntax WRITE [BREAK] [TRACE] [ALIASES] [>>] [filename]

WRITE required keyword

BREAK keyword to save the current breakpoints

TRACE keyword to save the current tracepoints

ALIASES keyword to save the current aliases

>> optional symbols before an output file

filename the name of the output file, with no extension

Write can be used to save in a file the commands to establish any or all of the current
debugging environment. The resulting output files can then be used as an initial-
ization file or, with a subsequent READ command, to reestablish the current
debugging session.

By default, if no other keyword appears in a WRITE command, all of the current

breakpoints, tracepoints and aliases are saved in the output file along with the source
file search path.

9-46 Four J’s Business Development Language User Guide

Keyword commands

If the >> symbols are included with a filename, the WRITE command assigns a name
to the output file by appending the extension .4db. If no filename is specified, WRITE
assigns a default name to the output file by appending the extension .4db to the
filename of the .42r or .42m file that is currently being debugged. If a .4db file with
the same name as the output file already exists, WRITE will append to it.

To save the output file to a directory other than the current directory, the filename
must be prefixed with a complete pathname.

The output from a WRITE command is plain text and may be subsequently amended
using an appropriate text editor. Additional commands may be included with the
exception of the non-keyword commands such as Interrupt, Screen or Toggle.

The output file may be edited to include READ commands that specify other .4db
input files up to a nesting level of 10. If READ commands are nested more than 10
deep, or if nested READ commands attempt to access each other, an error message
is displayed.

The >> symbols are optional and may be omitted wherever the name of the output
file cannot be confused with one of the options. For instance if a file called TRACE
is required, omitting the >> symbols will cause the debugger to interpret TRACE as
a command rather than a file name. Care should be taken with abbreviations, the
debugger will interpret T as an abbreviation for TRACE.

Examples:
WRITE >> strtdbg

The above command will save commands in the file strtdbg.4db in the current
working directory. Since no restriction is included, the output file will include all the
current breakpoints, tracepoints and aliases.

Related commands:

ALIAS, APPLICATION DEVICE, BREAK, LIST, READ, TRACE, USE

The Debugger 9-47

Keyword commands

9-48 Four J’s Business Development Language User Guide

Appendix

Environment Variables
A
This appendix provides a complete list of all environment variables for
use with Four J’s Business Development Language.

Some environment variables are only available on UNIX systems. The

description section states whether the environment variable is only
available on UNIX.

Four J’s Business Development

Language Environment Variables
This appendix provides a brief description of each environment
variable and the possible values you can set for it, with examples of
how to set the environment variable on the available platforms.
FGLGUI

FGLGUI
Description This environment variable determines if the Four J’s Business
Development Language programs will run with a character-based
ASCII user interface or a graphical user interface (GUI).

Values 0 or not set The 4GL application executes

using ASCII mode
1 The 4GL application executes
using graphical mode

Default 0 on UNIX

1 on Windows

Korn shell $ export FGLGUI=1 Korn shell

C shell $ setenv FGLGUI 1 C shell

Microsoft DOS C:\> set FGLGUI=1 Microsoft DOS

FGLDBPATH
Description This environment variable contains the paths to the schema files
of the databases used, separated by colons. The compiler does not
use the schema tables directly, but rather its own schema file gen-
erated by fglschema.

Values The path to the schema file

Default Set to the current directory

Korn shell $ export FGLDBPATH=/schema:$FGLDBPATH

C shell $ setenv FGLDBPATH "/schema:$FGLDBPATH"

Microsoft DOS C:\> set FGLDBPATH=C:\schema:%FGLDBPATH%

A-2 Four J’s Business Development Language User Guide

FGLDIR

FGLDIR
Description This environment variable contains the path to the installation
directory. This environment variable is required when you use
either the development package or the runtime package of Four
J’s Business Development Language.

Values The path to Four J’s Business Development Language

Default UNIX: /usr/fgl2c

Windows: C:\usr\fgl2c

Korn shell $ export FGLDIR=/usr/fgl2c

C shell $ setenv FGLDIR "/usr/fgl2c"

Microsoft DOS C:\> set FGLDIR=C:\usr\fgl2c

PATH
Description This system variable contains the path to the binary programs.
Add the path to the Four J’s Business Development Language
binary program.

Values The path to the binary directory

Korn shell $ export PATH=$FGLDIR/bin:$PATH

C shell $ setenv PATH $FGLDIR/bin:$PATH

Microsoft DOS C:\> set PATH=%FGLDIR%\bin:%PATH%

Environment Variables A-3

FGLCC

FGLCC
Description Available only on UNIX. This environment variable must be set
when you want to compile a new runner.

Value The name of the C or C++ compiler

Korn shell $ export FGLCC=gcc

C shell $ setenv FGLCC gcc

FGLRUN
Description This environment variable must be set to the name of the specific
P-code runner when linking P-code modules using fgl2p –o. Use
this environment variable for modules calling C functions that
have been linked to this runner by the fglmkrun utility.

Value The name of the runner that you currently use

Default FGLRUN=fglrun

Korn shell $ export FGLRUN=fglrun

C shell $ setenv FGLRUN fglrun

Microsoft DOS C:\> set FGLRUN=fglrun

FGLLDPATH
Description This environment variable provides the P-code runner with the
correct search path for P-code object files, which are dynamically
linked into an executable P-code program.

Value The path to the P-code modules

Default The current directory

A-4 Four J’s Business Development Language User Guide

FGLLIBSQL

Korn shell $ export FGLLDPATH=/modules:$FGLLDPATH

C shell $ setenv FGLLDPATH /modules:$FGLLDPATH

Microsoft DOS C:\> set FGLLDPATH=c:\modules:%FGLLDPATH%

FGLLIBSQL
Description Available only on UNIX. This environment variable specifies the
complete path to the SQL library, to link with the P-code runner or the
C-code programs that contain the interface functions to the database
server.

Value Complete path to the SQL library

Default $INFORMIXDIR/lib/libfesql.a

Korn shell $ export FGLLIBSQL=$INFORMIXDIR/lib/libfesql.a

C shell $ setenv FGLLIBSQL $INFORMIXDIR/lib/libfesql.a

Environment Variables A-5

FGLLIBSYS

FGLLIBSYS
Description Available only on UNIX. This environment variable specifies the list
of system libraries and flags needed to compile a P-code runner or C-
code programs.

Default Depends on your host operating system

Korn shell $ export FGLLIBSYS="-lm –lsocket"

C shell $ setenv FGLLIBSYS "-lm –lsocket"

FGLSQLDEBUG
Description If set to 1, this environment variable sends to the standard output
debugging information about your current SQL commands in a run-
ning 4GL program.

Value 0 disables the debugging feature

1 enables the debugging feature

Default 0

A-6 Four J’s Business Development Language User Guide

FGLDEBUGON

FGLDEBUGON
Description Available only on UNIX. This environment variable allows you to run
the X11 graphical server (fglX11d) in debug mode. Each operation
is redirected to the standard output. This option is not used for debug-
ging 4GL applications.

Value 0 or not set disables the debugging feature

1 enables the debugging feature

Default None

Korn shell $ export FGLDEBUGON=0

C shell $ setenv FGLDEBUGON 0

GCC Environment Variables

These environment variables are only available on UNIX.

CC
Description Available only on UNIX. This environment variable is set to
the name of the default compiler to use when compiling
C-language files.

Value The name of the compiler

Korn shell $ export CC="cc"

C shell $ setenv CC cc

Environment Variables A-7

GCC

GCC
Description Available only on UNIX. This environment variable specifies the
name of the GNU C Compiler.

Value The name of the GNU C compiler.

Korn shell $ export GCC=gcc

C shell $ setenv GCC gcc

GCCDIR
Description Available only on UNIX. This environment variable specifies the
directory in which the GNU C compiler is installed. This environment
variable is used only by Four J’s Business Development Language

Value The path of the gcc installation directory

Korn shell $ export GCCDIR=/usr/local/gcc-2.80

C shell $ setenv GCCDIR /usr/local/gcc-2.80

GCC_EXEC_PREFIX
Description Available only on UNIX. This environment variable specifies the
path of the installation directory of the GCC compiler.

Value Path to the gcc installation directory

Korn shell $ export GCC_EXEC_PREFIX=/usr/local/gcc-2.80

C shell $ setenv GCC_EXEC_PREFIX /usr/local/gcc-2.80

A-8 Four J’s Business Development Language User Guide

PATH

PATH
Description Available only on UNIX. This environment variable specifies the list
of directories where the operating system looks for a needed execut-
able file.

Value Path to the binary program

Korn shell $ export PATH=$GCCDIR:$PATH

C shell $ setenv PATH $GCCDIR/bin:$PATH

Tcl/Tk Environment Variables

These environment variables are available only on UNIX.

TCLDIR
Description Available only on UNIX. This environment variable is used only with
the Tcl/Tk package included in Four J’s Business Development Lan-
guage. This environment variable specifies the full path to the instal-
lation directory of the Tcl/Tk .

Value Complete path to the Tcl/Tk installation directory

Korn shell $ export TCLDIR=/usr/local

C shell $ setenv TCLDIR /usr/local

Environment Variables A-9

TK_LIBRARY

TK_LIBRARY
Description Available only on UNIX. This environment variable specifies the full
path to the TK library subdirectory.

Value Full path to the TK library subdirectory

Korn shell $ export TK_LIBRARY=/usr/local/lib/tk

C shell $ setenv TK_LIBRARY /usr/local/lib/tk

TCL_LIBRARY
Description Available only on UNIX. This environment variable specifies the full
path to the TCL library subdirectory.

Value Full path to the TCL library subdirectory

Korn shell $ export TCL_LIBRARY=/usr/local/lib/tcl

C shell $ setenv TCL_LIBRARY /usr/local/lib/tcl

PATH
Description Available only on UNIX. This environment variable specifies the list
of directories where the operating system looks for a needed execut-
able file.

Value Path to the binary program

Korn shell $ export PATH=$TCLDIR/bin:$PATH

C shell $ setenv PATH $TCLDIR/bin:$PATH

A-10 Four J’s Business Development Language User Guide

Appendix

Hints, Tips and

Workarounds B
This appendix contains information about how to resolve issues in the
following areas:

• Installing the Four J’s BDL software manually

• The interruption signal
• The P-code runner and C-code compilation
• Special characters and the GLS feature
• The Windows Client
• 4GL program errors
• Distributing the workload on workstations with Windows
• HP-UX ELF-64 bit support (PA-RISC 2.0)

Installing the Four J’s Business

Development Language Software
Manually
If you have problems installing the Four J’s BDL software, you can
perform a manual installation.

Logging On and Loading the Files

Log on as root. If you have an earlier version of the software on your
system, make sure no one is using it during the installation of the new
one, and stop all Four J’s BDL daemons.
Manual Installation Process

Files with the extension .tgz are compressed archive files. To uncompress this kind
of file, you must first run gzip and then tar with the following commands:
$ gzip -d filename.tgz
$ tar xvf filename.tar

Before uncompressing the file with tar, you can view its contents with the following
command:
$ tar tvf filename.tar

Distributions on tapes can be loaded with the following commands:

$ cd /tmp
$ tar xvf /dev/your_device

On the distribution CD, you will find all the necessary files in the /OS/UNIX/your OS
name directory.

Manual Installation Process

The archive file is assumed to be named:
F4GL.TGZ

This archive file contains a complete directory tree, which can be installed anywhere.

A convenient way to proceed is:

$ mkdir installdir/f4gl.version
$ cd installdir/f4gl.version
$ FGLDIR=installdir/f4gl.version
$ export FGLDIR
$ INFORMIXDIR=Path_to_Informix_directory
$ export INFORMIXDIR
$ cp path_to_gzip_file .
$ gzip -d F4GL.TGZ
$ tar xvf F4GL.tar

where installdir is the path to the installation directory. The following examples illus-
trate how to do both a new installation and an update.

B-2 Four J’s Business Development Language User Guide

Manual License Installation

For a new installation:

$ mkdir /usr/f4gl
$ cd /usr/f4gl
$ FGLDIR=/usr/f4gl
$ export FGLDIR
$ INFORMIXDIR=/usr/informix4.1
$ export INFORMIXDIR
$ cp CD/OS/UNIX/SCO/COMPILER/F4GL.TGZ .
$ gzip -d F4GL.TGZ
$ tar xvf F4GL.tar

For an update, first make a backup of your earlier version:

$ mkdir /usr/f4gl.save
$ cd /usr/f4gl
$ tar cvf /usr/f4gl.save/f4gl-version.tar .
$ gzip /usr/f4gl.save/f4gl-version.tar

Now you can install the new one:

$ cp CD/OS/UNIX/SCO/COMPILER/F4GL.TGZ .
$ gzip -d F4GL.TGZ
$ tar xvf F4GL.tar

Manual License Installation

To install or reinstall a license, the FGLDIR environment variable has to be set to the
directory where you have installed the product, and the $FGLDIR/bin directory has
to be added to your PATH variable. Then execute the following commands:
$ cd $FGLDIR/bin
$ licencef4gl

This will start the license installation process, as described in “Licensing the Product”
on page 2-4.

Post-Installation Tasks
If you are doing a manual installation, you need to complete the following procedures
by hand before you can use Four J’s BDL. If you are performing an automatic instal-
lation, these tasks are done for you.

Hints, Tips and Workarounds B-3

Post-Installation Tasks

The C Compiler
During this phase, you might need a C compiler. It is required if you plan to create a
new runner or if you want to compile your 4GL programs to C code. But it is not used
afterward for P-code compilation. You can use either the native C compiler of the
computer or the C compiler of the GNU tools, included on the distribution media.

If there is no usable native C compiler on your computer, the GNU tools must be
installed. However, you still need to have your UNIX system libraries installed.

To install the GNU C compiler from the Four J’s BDL CD, go into the OS/UNIX/
directory and run the following command:
$ /bin/sh ./insttgcc –i

This shell script installs the package GCC.TGZ located in the directory
/OS/UNIX/your_OS_name/GNUC.

If you cannot mount the CD directly on UNIX, you can copy the file gnuc.sh, located
in the directory /OS/UNIX/your_OS_name/SELFEXTR, to a temporary directory on
UNIX. Use binary transfer mode because this shell script contains all the files of the
GNU C compiler. Then run the following command to start the installation:

$ /bin/sh ./GNUC.SH -i

During the installation process, you will be prompted for the installation directory of
the GNU C compiler. A shell script named envgcc will also be generated during the
installation. You must execute this shell script to set all the environment variables
needed for compiling and linking C programs.

Tip: This distribution does not contain the system libraries you need to compile C
sources. To obtain those libraries, contact your operating-system reseller.

If you plan to link a runner without any C functions, you only need to install a linker
and not an ANSI-C compliant compiler.

If you are not using the default C compiler (normally cc), make sure that you have
set the INFORMIXC environment variable to the compiler you are using (such as gcc
for the GNU C compiler,) as well as the documented FGLCC and CC variables. For
example:
INFORMIXC=gcc
export INFORMIXC

B-4 Four J’s Business Development Language User Guide

Post-Installation Tasks

Finding the Required Libraries: findlib.sh

The first step is to identify the Informix libraries, the UNIX system libraries, and the
Four J’s BDL libraries needed to create the libraries and the P-code runner. To do so,
run the findlib.sh Bourne shell script located in the bin subdirectory where Four J’s
BDL is installed. This step requires a C compiler and the INFORMIX-ESQL/C devel-
opment libraries:
$ /bin/sh ./findlib.sh

This script generates a file called envcomp in the local directory. This shell script sets
all the environment variables necessary to create the P-code runner and the 4GL
libraries, which allow you to compile to C code and to execute 4GL programs.
Execute this Bourne shell script with the following command:
$ ./envcomp

Creating the P-Code Runner and Libraries

You are now ready to create the P-code runner. This runner contains all the routines
to access to the Informix database with your version of the Informix database
interface. This runner is used when you link your 4GL source code modules together
and when you run the P-code compiled 4GL programs.

The runner is the result of linking your Informix libraries, your UNIX system
libraries, and the Four J’s BDL libraries. Each time that one of these three compo-
nents changes, you must create a new runner. If you have C functions, you must also
include them in the runner. For more information about using C functions with 4GL,
see “Using C Functions in 4GL Applications” on page 4-9.

Important: Creating the P-code runner for your computer requires a C compiler
and the INFORMIX-ESQL/C development libraries.

To build a P-code runner, type:

$ fglmkrun

This command creates the default P-code runner, called fglrun, in the $FGLDIR/bin
directory.

Hints, Tips and Workarounds B-5

Post-Installation Tasks

If you need your own, statically-linked runner, use the syntax in the following
example (assume your runner is named myrun, you are using Informix Client SDK
version 2.10, and using a C function file named file.c):
$ fglmkrun -d ix914 -add -static $FGLDIR/lib/fglExt.c
file.c -o myrun

After you have successfully created the P-code runner, run the rtsinstall command
to create the P-code libraries and tools:
$ rtsinstall

For details about fglmkrun, see “Details About fglmkrun” on page 4-13.

SCO Systems
With SCO systems, the use of fglmkrun during a manual installation might cause the
following error message:
Symbol not found
First referenced in file
fileno .../lib/libf2c.a

The solution is to first create a file named fileno.c that contains the following code:
#include stdio.h
#undef fileno
int fileno(f)
FILE *f ;
{
return(f->__file) ;
}

Next, execute fglmkrun with fileno.c as an additional parameter (for Informix

Version 5.x):
$ fglmkrun -o fglrun fileno.c $FGLDIR/lib/fglExt.c

This creates the runner named fglrun in the current directory.

Creating the C-Code Libraries

If you have Version 6.x or Version 7.x Informix database servers, set the FGLDBS
environment variable with ix711:
$ FGLDBS=ix711
$ export FGLDBS

B-6 Four J’s Business Development Language User Guide

Interruption Signal

Then run the fglinstall program in order to compile the C-code libraries and tools:
$ fglinstall

You are now ready to compile 4GL programs on UNIX.

Interruption Signal
When you press the interrupt key or the Interrupt button, your client computer inter-
cepts this and sends it to the server. It is not possible to send an interrupt signal over
the network, so Four J’s BDL sends an MSG_OOB (out of band) message through the
connected socket, which is the real interrupt message for network operations.

Usually, the application server receives this signal and stops the application.
Problems can occur in the following situations:

• The client TCP/IP stack does not support the OOB message. This is often
the case with the TUN TCP/IP stack from ESKER. In this case, you must
disable the OOB functionality. The compiler will then send a whole
command over the network to the server computer to stop the application.
Add the following line in your fglprofile file:
gui.useOOB.interrupt=0
• The application server TCP/IP stack does not handle OOB signals. In this
case you must also disable the OOB mechanism and use the following
setting in the fglprofile:
gui.useOOB.interrupt=0

Hints, Tips and Workarounds B-7

P-Code Runner and C-Code Compilation

• The application server uses a different code number for the OOB
message. Some systems use different signals to code the OOB message. For
example, the signal number changed between SCO OPEN SERVER 5.02 and
SCO OPEN SERVER 5.04. To determine the received signal that your system
uses, add the following line in your fglprofile:
fglrun.signalOOB= -1
Then execute a 4GL program and press the interrupt key multiple times. You
will see messages similar to the following message on your terminal:
Enable trappings of signal
Received signal is 18
(18 is subject to change depending on systems)
Hit your interrupt key twice:
Received signal is xx
Received signal is xx
The value xx is returned by your operating system when an OOB message is
received on a socket. You can specify this number in the fglprofile file with
the entry:
fglrun.signalOOB= xx

P-Code Runner and C-Code Compilation

This section describes how to specify which Informix libraries to use and how to find
missing system libraries on UNIX.

Finding Informix 7.x Libraries on UNIX

The best way to specify the list of Informix libraries to use is to set the FGLLIBSQL
environment variable to that list. This list of libraries changes, depending on the
version of ESQL/C and the operating system. This section describes a convenient way
to find out which libraries are used if the findlib.sh script failed to find them.

If you are using ESQL/C, copy the script $INFORMIXDIR/bin/esql to an empty

directory. Modify this copy in order to echo the linking command. For example:
echo $CC -I$INFDIR/incl/esql $INCLUDE $A -L $INFDIR/lib \
-L $INFDIR/lib/esql $SLIB $OLIB $ALIB

B-8 Four J’s Business Development Language User Guide

Finding Informix 7.x Libraries on UNIX

Write a small ESQL/C File. For example, t.ec:

main(argc,argv)
int argc; char *argv[];
{
}

Compile it using your copy of ESQL:

$ ./esql t.ec

This gives you the compile statement with all the libraries used on the standard
output. For example:
cc -I/usr1/informix7.11/incl/esql t.c -L /usr1/informix7.11/lib -L
/usr1/informix7.11/lib/esql -L /usr1/informix7.11/lib/esql
/usr1/informix7.11/lib/esql/libsqlshr.a -L
/usr1/informix7.11/lib/esql /usr1/informix7.11/lib/esql/libosshr.a
-L /usr1/informix7.11/lib /usr1/informix7.11/lib/libasfshr.a -L
/usr1/informix7.11/lib/esql
/usr1/informix7.11/lib/esql/libgenshr.a -L
/usr1/informix7.11/lib/esql /usr1/informix7.11/lib/esql/libosshr.a
-L /usr1/informix7.11/lib/esql
/usr1/informix7.11/lib/esql/libgenshr.a -ltli -L
/usr1/informix7.11/lib /usr1/informix7.11/lib/libnetstubshr.a -lc
-lmsaa -lbsd

In this case, you would have to set your environment variable FGLLIBSQL like this:
$ export FGLLIBSQL"$INFORMIXDIR/lib/esql/libsqlshr.a
$INFORMIXDIR/lib/esql/libosshr.a
$INFORMIXDIR/lib/libasfshr.a
$INFORMIXDIR/lib/esql/libgenshr.a
$INFORMIXDIR/lib/esql/libosshr.a
$INFORMIXDIR/lib/esql/libgenshr.a
/usr/lib/libtli.a
$INFORMIXDIR/lib/libnetstubshr.a
/usr/lib/libc.a
/usr/lib/libmsaa.a
/usr/lib/libbsd.a "

If you do not have ESQL/C development but only 4GL development on your system,
the way to proceed is similar to that with ESQL/C, except that you will copy and
modify the script $INFORMIXDIR/bin/c4gl and use the copy to compile a 4GL
example, but then you must remove the libraries from the list that are specific to
INFORMIX-4GL.

Hints, Tips and Workarounds B-9

Finding System Libraries on UNIX

Finding System Libraries on UNIX

On some operating-system implementations, the libraries might have been split.
When linking, you might discover some undefined symbols. For example, if the
findlib.sh script failed to find the required libraries, one way to find the missing
libraries would be as follows.

Given a missing function named funcname, execute the following UNIX shell
command:
$ for i in /lib/*.a /usr/lib/*.a
>do
> echo $i
>nm $i | grep funcname
>done | pg

If the result looks like:

/usr/lib/libname.a
funcname| 1640|glob | | 0

and the first number is greater than zero (here it is 1640), the library libname.a must
be added to the list of the system libraries needed to create a P-code runner or a C-
code application. This list is specified by the FGLLIBSYS environment variable and
is built in the same way as FGLLIBSQL.

Special Characters with Informix 7.2x and

higher
If a program aborts when you use special characters (for example, a German diaeresis
or a French accent) in a CONSTRUCT, it is because Global Language Support (GLS)
is active with Informix 7.2x database servers.

When you create the database, you must set the environment variable DB_LOCALE.
If it is not set, the database will be installed with U.S. English locale (en_US.859-1.)

You can view the current configuration with the following SQL statement:
SELECT * FROM systables WHERE tabid IN (90,91).

B-10 Four J’s Business Development Language User Guide

4GL Program Errors

If the database is not created with the correct configuration, it must be unloaded with
dbexport, dropped, and imported with the dbimport command and with the
DB_LOCALE environment variable set to the proper value (for example,
de_de.8859-1 for German).

To see which local versions are supported, run:

$INFORMIXDIR/bin/glfiles

This command will create the file lcll.txt in which you see the supported versions.

4GL Program Errors

This section describes workarounds to use if you experience errors with your 4GL
program.

Internal Data File Corrupted

On some UNIX systems (for example, SCO), you might receive the following error
message:
Internal data file corrupted. Cannot continue this program.

After that, your program fails.

This failure occurs because the process table of UNIX systems is used to retrieve
internal information. This information is stored in the $FGLDIR/lock directory. To
view this table, use the UNIX command ps –ae.

Normally, this gives the complete list of processes. But on some operating systems
(such as SCO), you see only the processes of the current user if you are not the
superuser.

If you receive the error message, check your UNIX documentation for a command
that gives the complete list of processes and then set the environment variable FGLPS
to this value. For example:
FGLPS="ps -aefx"
export FGLPS

Hints, Tips and Workarounds B-11

Values of Streams on SCO Computers

If there is no command that allows a non-superuser to view the whole process list on
the operating system, you can use the following procedure (you need a C compiler
installed on your computer):

• Log in as root:
$ cd $FGLDIR/src
• Edit the file psall.c and change the «ps -ae» command if needed:
$ cc -o psall psall.c
$ cp psall $FGLDIR/bin
$ cd $FGLDIR/bin
$ chown root psall
$ chgrp root psall
$ chmod 0755 psall
$ chmod a+s psall

Add to your environment file (for example: .profile, envcomp, $FGLDIR/envf4gl)

the lines:
FGLPS="psall"
export FGLPS

It is also possible that the file system is full and the 4GL application cannot create the
internal data files in the $FGLDIR/lock directory. Use the command df to check
whether you have enough free space on the file system where Four J’s BDL is
installed.

Values of Streams on SCO Computers

Stream values must be big enough, depending on the UNIX node (using TCP, NFS, or
other nodes).

To check if the stream size is large enough, log in as root, use the «crash» command
and the «strstat» command. The values in the FAIL column must always be zero.

B-12 Four J’s Business Development Language User Guide

SCO Open Server 5 and GCC Compiler

For example:
# crash (
dumpfile = /dev/mem, namelist = /unix, outfile = stdout
> strstat (
ITEM CONFIGALLOC FREE TOTAL MAX FAIL
streams 512 52 460 75 53 0
queues 1424 240 1184 172 244 0
message blocks 6258 124 6134 3673 269 0
data block totals 5007 124 4883 3103 198 0
data block size4 512 21 491 207 29 0
data block size16 512 3 509 428 67 0
data block size64 512 31 481 2115 40 0
data block size1282048 54 1994 242 57 0
data block size2561024 15 1009 55 17 0
data block size512256 0 256 28 1 0
data block size102452 0 52 9 1 0
data block size204850 0 50 14 1 0
data block size409641 0 41 5 1 0

SCO Open Server 5 and GCC Compiler

SCO Open Server 5 file format is ELF 32b. The GCC compiler provided by Four J’s
BDL uses file format COFF (and produces COFF binary files). Therefore, do not
install GCC on this host server; instead, use your native host C compiler, which
understands the COFF file format.

If you receive the following error after compiling:

undefined symbol __write in $FGLDIR/lib/libgcc.a

use the following procedure:

• Create file dummywrite.c with the following lines :

int __write(int fd, char *c, int l) {
return(write(fd,c,l));
}
• Compile the file dummywrite.c with your native C compiler.
• Execute the shell command «ar» and apply it to the library
$FGLDIR/lib/libgcc.a as follows:
cd $FGLDIR/lib
rv libgcc.a dummywrite.o

Now you are ready to link your runner.

Hints, Tips and Workarounds B-13

Key Buttons Missing

Key Buttons Missing

If you are using an SCO system and no key buttons appear, change the dot (.) to a
comma (,) in the In /usr/lib/lang/$LANG/*/*/numeric file.

To test, call wish or tclsh, and try expr 3.4 + 3 or expr 3,4 + 3. One of them must
run. Our syntax uses the dot. Here is an example:
LANG=german

in /usr/lib/lang/german/germany/*/numeric.

You cannot make the modification directly with a text editor. You have to look at the
file with od -c numeric. For example, if you get:
00000000 002 , . \0 \0 \0
00000005

then you must use the command:

$ echo -n "\002.,\000\000 > numeric

Make sure you save the original version. You should then see the file as:
00000000 002 . , \0 \0 \0
00000005

Common Problems on Windows Platforms

This section describes workarounds for problems with Windows NT and
workarounds for problems that involve UNIX-to-Windows configurations.

Problems with the File fgl2c tcl on Windows NT

Never change or edit fgl2c.tcl on Windows NT. If you do that, ^M characters are
automatically added to the end of each line, and the WTK client will not run.

B-14 Four J’s Business Development Language User Guide

Problems Using the rcp Command

Problems Using the rcp Command

If you do not have permission to use the rcp command from the UNIX side to access
a Windows computer having Ataman remote login services installed, perform the
following steps:

• On Windows, display the Advanced page in the Ataman TCP Remote

Logon Services dialog box.
• In the Rshd and Rexecd areas, leave the List of hosts allowed to connect
field empty.
This disables both functions because you already have them with the Win-
dows Client, and they can cause some conflicts.

Terminal Emulation Issues

With Windows front-end terminal emulation, when you open a file with vi and use
the DOWN ARROW key to move the cursor down for more than one page, the lines are
often displayed on the same line on the bottom of the screen without scrolling the
previous lines upward.

This occurs because with Windows you have a 25-line terminal. To fix this problem,
in xterm termcap, change the definition from li#24 to li#25. On some systems, you
can also export the LINES environment variable set to 25.

Memory Fault with ESQL 7.20.TD1 with Windows NT

4.0
Informix ESQL/C, Version 7.20.TD1 with Windows NT 4.0, causes a memory fault
with some Informix instructions (for example, UNLOAD). You must use ESQL
7.20.TE1 to fix this problem.

Hints, Tips and Workarounds B-15

How to Start a Windows Program from the UNIX Server

How to Start a Windows Program from the UNIX Server

From Linux, enter the following command:
$ rsh PC_name "winexec progname.exe"

From your UNIX system, enter the following command:

$ rcmd PC_name "winexec progname.exe"

To open a file directly, enter:

$ rcmd PC_name "winexec \"progname.exe c:/autoexec.bat\""

The graphical daemon must be running when you try this command.

Distributing the Workload on Workstations with

Windows

Normally, a standard Four J's BDL configuration follows the "thin client" archi-
tecture: The 4gl programs are executed on an application server and the workstations
are only in charge of the user interface, using the Windows Front End.

However, in order to distribute the work on all the machines, you can run the 4gl
applications on the workstations without installing the Four J's BDL runtime on each
machine. Only the database client software must be installed and configured on each
workstation, to let 4gl application connect directly to the database server.

Steps to configure your machines for distributed workload:

1. Select a Windows Server to be the file server. We will assume this machine
is identified by the hostname "FS".
2. On the FS, create a directory to hold Four J's products. For example,
C:\FOURJS.

B-16 Four J’s Business Development Language User Guide

Distributing the Workload on Workstations with Windows

3. Install the Four J's BDL product on the FS under the Four J's directory, for
example into C:\FOURJS\F4GL. You must install the product with a license
server. The license server is mandatory to check the license from the
machines where 4gl applications will be executed.
4. On the FS machine, set the following FGLPROFILE entry to define where
the license server is running:
fgllic.server = "FS"

This entry will be used by the 4gl programs to find the license server
on the network. Additional configuration parameters can be set to
customize the licensing service, like tcp service, timeout or local data
storage. See the FGLPROFILE configuration file for more details

5. Make sure the license server is running on the FS machine. Run the license
manager utility to see the current status.
6. To read the BDL files from the workstations on the file server FS, create a
network share (i.e. \\FS\FJS) to the Four J's installation directory
(C:\FOURJS). Make sure you are using a correct user policy (i.e. with
domain users) to give access to the files.
7. On the FS machine, create a network share (i.e. \\FS\APP) to your 4gl
programs in order to access these file from the workstations for execution.
8. Select a Windows machine to act as a workstation. We will assume this
machine is identified by the hostname "WS".
9. Install the Windows Front End on the WS workstation. See the Windows
Front End documentation for more details.
10. To access the Four J's BDL files from the WS, use the file explorer to map
the \\FS\FJS network drive. We will assume this mapping to be identified as
a drive with the letter "F".
11. To access your 4gl program files, use the file explorer to map the \\FS\APP
network drive. We will assume this mapping to be identified as a drive with
the letter "G".
12. To execute 4gl applications on the WS, set following environment
variables:
set FGLDIR=F:\F4GL
set PATH=%FGLDIR%\bin;%PATH%
set FGLLDPATH=G:\
set FGLGUI=1
set FGLSERVER=WS:0

Hints, Tips and Workarounds B-17

Distributing the Workload on Workstations with Windows

13. Make sure you have a database server available on your network. In this
example we call the database server DS. Usually the file server (FS) and the
database server (DS) are the same machine.
14. Install the Database Client Software on each workstation.
Informix example: Install Informix Connect corresponding to the
Informix server you want to access. See Informix documentation for
details.

15. Configure the client software to access the DS database server.

Informix example:

Use the SETNET32 Informix client configuration utility:

Define the Informix environment in the first folder. You must define
INFORMIXDIR and INFORMIXSERVER. INFORMIXSQL-
HOSTS defines the Windows machine where the Informix server
definitions can be found (SQLHOSTS).

B-18 Four J’s Business Development Language User Guide

HP-UX 11.X ELF-64 bit support (PA-RISC 2.0)

Warning: If you use a central Windows registry by setting INFOR-

MIXSQLHOSTS, make sure your Windows machines have the
services to share the registry over the network.

Warning: This environment is specific to the current Windows user.

Data is saved in the registry key HKEY_CURRENT_USER!

Define the Informix server (SQLHOSTS) in the second folder:

Identify the Informix server with a name (INFORMIXSERVER), a
hostname, a protocol and a service. If you use a named TCP service,
make sure this TCP service is defined in:
WINDIR\system32\drivers\etc\services

Define a user identification (netrc) to connect to the database server

in the third folder.

Warning: Only the 'password' mode is supported by Four J's BDL.

Warning: This login and password is specific to the current Windows
user. Data is saved in the registry key HKEY_CURRENT_USER!

Test the Informix client configuration with the 'ilogin' demo

program. If you face problems, see the Informix Connect documen-
tation for more details.

HP-UX 11.X ELF-64 bit support (PA-RISC 2.0)

Four J’s BDL is available on UNIX HP-UX 11.X in ELF-64 bit format, subject to the
following prerequisites:

Warning : Check the following prerequisites before installing Four J's BDL.

Hints, Tips and Workarounds B-19

HP-UX 11.X ELF-64 bit support (PA-RISC 2.0)

Informix-ESQL/C Version:
The INFORMIX-ESQL/C version supported is version 9.30.FC1 or higher. The
version of esql can be checked with the -V option :
$ esql -V
INFORMIX-ESQL Version 9.30.FC1
Software Serial Number XXX#Z123456

Note: FCx means a 64bit versions

Native C/C++ compiler:

The native C/C++ compiler provided by HP may be used with the options to generate
64bit binaries. See HP C development documentation for more details.

Example using a small C source:

$ c es.c
main(){
int a=0;
a++;
}

$ cc -v +DS2.0 +DA2.0W -o es es.c

$ file es

es: ELF-64 executable object file - PA-RISC 2.0 (LP64)

GNU gcc compiler:

To use the GNU compiler, we suggest the bin version is downloaded from the HP
site:
http://devresource.hp.com/OpenSource/Tools/GnuPro.html

No specific option should be needed to compile C programs in 64bit:

$ gcc -v -o es es.c
$ file es

B-20 Four J’s Business Development Language User Guide

HP-UX 11.X ELF-64 bit support (PA-RISC 2.0)

es: ELF-64 executable object file - PA-RISC 2.0 (LP64)

In order to use the GNU compiler with the esql tool provided by INFORMIX, the
script must be modified as it was not designed to work with gcc.
Before doing any modification, make a copy of esql (found in the $INFOR-
MIXDIR/bin directory).

Edit the esql script and modify the lines defining the C compiler and the compilation
options :
CC=${INFORMIXC=cc}

becomes
CC=${INFORMIXC=gcc}

and
COPTS="-Wp,-H400000 +Ofastaccess +DS2.0 +DA2.0W"

becomes
COPTS="-Wp,-H400000"

Options +Ofastaccess +DS2.0 +DA2.0W are not gcc options, but are specific to the
native HP C compiler.

Using 32bit on 64bit machines

HP/UX 64 bit systems support 32 bit executables, therefore an HP 32 bit version of
Four J's BDL can be installed on a HP 64bit machine.

Hints, Tips and Workarounds B-21

HP-UX 11.X ELF-64 bit support (PA-RISC 2.0)

B-22 Four J’s Business Development Language User Guide

Appendix

Global Language
Support C
This appendix describes the Global Language Support (GLS) feature
available in Four J’s BDL. The GLS feature allows Informix database
servers to handle different languages, cultural conventions, and code
sets.

This appendix describes the GLS features unique to Four J’s BDL. You
should be familiar with using GLS features and GLS behaviors before
using this appendix.

For Additional GLS Information

For additional information on using GLS, refer to the following
Informix guides:

• GLS Programming Guide included with the Informix

Dynamic Server 7.2x (or greater) documentation.
• Informix Guide to GLS Functionality included with the
Informix Dynamic Server 7.2x (or greater) documentation.

Informix guides are available from the Informix Online Documentation

web site. To access this web site, use the following URL:
http://www.informix.com/answers

All manuals listed on the Web site are stored in Adobe Acrobat (.pdf)
format.
Software Requirements

Software Requirements
You do not need 4GL installed to install Four J’s BDL. However, the Client SDK,
Version2.x or later, must be installed.

The Client SDK installs the latest version of GLS. To use the GLS feature in Four J’s
BDL, you must be using Informix GLS 3.07 (or later).

Displaying the GLS Version

To display the currently installed version of GLS, enter the following:
cat $INFORMIXDIR/etc/GLS-cr

and the GLS copyright message will be displayed. For instance:

INFORMIX LIBGLS LIBRARY Version 3.08.UC1
Copyright (C) 1991-1998 Informix Software, Inc.

Downloading the Client SDK

The latest version of the Client SDK is available for download from the Informix Web
site at the following URL:
http://www.intraware.com/informix/

Supported Four J’s Business Development Language

Clients
The clients able to run Four J’s BDL applications with the GLS feature enabled are:

• Windows Client
• Text (ASCII) Client
• Java Client

The Four J’s BDL clients that do not support all languages are:

• X11 Client
• HTML client

C-2 Four J’s Business Development Language User Guide

Database Server Compatibility

Database Server Compatibility

This section describes the compatibility of Four J’s BDL with Informix database
servers and other Informix products.

To use the GLS features of Four J’s BDL, any database or connectivity products must
support the Informix GLS library, Version 3.07 or higher. Figure C-1 summarizes the
relationships of Four J’s BDL to the UNIX-based Informix database servers that are
supported.
Figure C-1
Database
7.x GLS OnLine/SE Servers that are
supported
by Four J’s BDL
7.x English OnLine/SE
Four J’s BDL
(with NLS)

5.x ALS OnLine/SE

(Taiwanese, Japanese,
Chinese, Korean)
Complete compatibility
5.x English OnLine/SE
Asian product behavior is
dependent on server version
English and NLS supported; English will not
cause problems if DB_LOCALE = en_us.8859-1

English will not cause problems if DB_LOCALE = en_us.8859-

Informix 7.2 and later GLS servers can store and retrieve data values that are
compliant with single-byte and multibyte locales. GLS functionality requires the GLS
version of INFORMIX-NET PC.

Four J’s BDL is also compatible with Informix 5.x and 7.1 database servers, which
can be English or non-English based.

Four J’s BDL also supports older (ALS-based) Informix servers. The functionality
differences are server-version based; applications may behave differently when
connected to different servers.

Global Language Support C-3

Restrictions on Four J’s Business Development Language GLS Capability

Restrictions on Four J’s Business Development

Language GLS Capability
When using Four J’s BDL, the following restrictions apply:

• GLS features must be compiled to P code. Programs compiled to C code

cannot be localized using GLS.
• GLS features in Four J’s BDL are restricted to locales that use left-to-right
text processing.
• Four J’s BDL supports the entry, storage, and display of multibyte
characters in some East-Asian languages, such as Korean, Japanese, and
Chinese. However, these GLS features require a localized version of
Windows.
• Four J’s BDL provides limited support for the Thai language through code
set th_th.thai620, with Language Supplement TH 7.20, for non-composite
Thai characters. (Four J’s BDL does not support composite Thai
characters.)

Creating Four J’s Business Development Language

Applications with GLS Support
This section outlines the steps that are needed to create localized Four J’s BDL
applications:

1. Set up the development environment.

The system administration tools you use must belong to the database server.
You can use a UNIX terminal or a local terminal-emulation program on
Windows (provided that it supports the local code set).
2. Write the code.
Filenames (source and compiled) must contain only English characters.
3. Compile and debug the code.
The Four J’s BDL compiler can compile and link the components of the
application.
The fglmkmsg message compiler can compile non-English text strings so
that runtime messages can be displayed in the local language. The user inter-
face of this message compile is in English.
Any Windows help requires the Windows Help Compiler.

C-4 Four J’s Business Development Language User Guide

Compiling a Four J’s Business Development Language Application with GLS

4. Deploy the code.

Deployment is relatively unrestricted. Applications that can be created
through the steps outlined here are localized applications for a specific
locale, and therefore are not internationalized. (That is, they should not be
used in another locale that requires, for example, a different code set from
that of the message files.)

Compiling a Four J’s Business Development Language

Application with GLS

Selecting tools version

Four J’s provides both ASCII and a GLS versions of the tools, located in
$FGLDIR/bin/ascii and $FGLDIR/bin/gls respectively. Using the fglmode utility,
you can automatically switch all Four J’s BDL tools from GLS to ASCII or ASCII to
GLS modes. Run fglmode with the -h option for more details or refer to “fglmode”
on page 4-42.

Creating a Runner
To create a GLS runner, add the -gls flag when running the fglmkrun script.

For example:
fglmkrun -o myrunner -gls

By default, the runner will be created in the $FGLDIR/bin/gls directory and linked to
an alias in the $FGLDIR/bin directory.

If the application is to run with Informix 7.3 database servers or higher, set the -d
fglmkrun flag to ix914 in order to use the Informix Esql/C 9.1x database interface.
Alternatively, you can set the FGLDBS environment variable to this value.
If you do not specify the -gls flag when running the fglmkrun script, an ASCII runner
(supporting only 8 bits ISO 8859-1 character set) will be created in the
$FGLDIR/bin/ascii directory and linked to an alias in the $FGLDIR/bin directory.

To create a GLS P code runner on NT with the winrunr.mk makefile, you must set
the USE_GLS variable to YES.

Global Language Support C-5

Checking if a Runner with GLS Support was Created

For example:
nmake %FGLDIR%\lib\winrunr.mk RUNNER_IX9=myrun.exe
RUNNERS_TO_MAKE=myrun.exe USE_GLS=YES

Ensure you have the right environment settings for compilation.

For more information read the header of the file %FLGDIR%\lib\winrunr.mk.

Checking if a Runner with GLS Support was Created

You can check if a runner was created with GLS support by using the -V flag. A
runner with GLS support enabled will display:
$ fglrun -V
Four J’s Business Development Language Runner Version 3.00
Built June 30 1999 15:36:04
(c) 1989-1998 Four J's Development Tools
Language support library: GLS (INFORMIX-ESQL Version 9.16.UC2)
Database front end : INFORMIX-ESQL VERSION 9.14(a)

A runner without GLS support enabled and using only ASCII characters will display:
$ fglrun -V
Four J’s Business Development Language Runner Version 3.00
Built June 30 1999 15:36:04
(c) 1989-1998 Four J's Development Tools
Language support library: standard ASCII (ISO8859-1)
Database front end : INFORMIX-ESQL VERSION 9.14

Localizing Four J’s Business Development Language

Messages
Four J’s BDL displays messages differently, depending on whether the message was
generated by SQL functions or not.

Messages Generated by SQL functions

Messages generated by internal calls to SQL functions are retrieved using the
Informix rgetmsg ( ) function.

C-6 Four J’s Business Development Language User Guide

Using the Forms Compiler

Four J’s Business Development Language Messages

Four J’s BDL messages are stored in the
$FGLDIR/<lang_state>/<codeset-id>/all.msg file. In addition, Four J’s BDL
creates a subset of messages files that are similar to i4gcl, c4gl, and form4gl Informix
messages and stores them in $FGLDIR. Four J’s BDL uses these message files during
compilation.

fglprofile Localized Messages

Message strings in the fglprofile are replaced by a link to a message number. If no
message is found that corresponds to this number, the help message label appears.
You can replace the message label with any string.

Before:
key.help.text=”help”

After:
key.help.text= [msg -6900 “help”]

Using the Forms Compiler

The fglform forms compiler can process form specifications that include non-
English characters that are valid in the client locale. It can also produce compiled
forms that can display characters from the client locale and accept the input of such
characters from the user.

Using the Message Compiler

The fglmkmsg message compiler can compile messages that include non-English
characters, so that runtime messages can be in the local language. The ERR_GET( )
function can display locale-dependent characters.

Fully-Supported Windows Toolkit (WTK) Character

Sets
Windows Toolkit (WTK) is the

Global Language Support C-7

Fully-Supported Windows Toolkit (WTK) Character Sets

software that customizes the Tcl/Tk for GUIs on Windows. The following WTK
character sets can be used with Four J’s BDL and are fully supported by Microsoft.

Important: You should refer to the Four J’s BDL Release Notes for any changes to
the supported WTK character sets.

Microsoft Code
Code Set Character Set Name or Alias Page ID

1252 ANSI_CHARSET, Western, 1252

west-europe Windows-1252
cp1252
1250 EE_CHARSET, Central european (Windows), 1250
east-europe Windows-1250, x-cp1250
cp1250

1251 RUSSIAN_CHARSET, Cyrillic (Windows), 1251

pc-slavic Windows-1251, x-cp1251
cp1251

1253 GREEK_CHARSET, Greek (Windows), 1253

pc-greek Windows-1253
cp1253

1254 TURKISH_CHARSET, Turkish (Windows), 1254

pc-latin5 Windows-1254
pc-turkish
cp1254

1255 HEBREW_CHARSET, Hebrew 1255

pc-hebrew Windows-1255
cp1255

1256 ARABIC_CHARSET, Arabic 1256

pc-arabic Windows-1256
cp1256

1257 BALTIC_CHARSET, Baltic Windows-1257 1257

pc-baltic
cp1257
(1 of 2)

C-8 Four J’s Business Development Language User Guide

Fully-Supported Windows Toolkit (WTK) Character Sets

Microsoft Code
Code Set Character Set Name or Alias Page ID

1258 VIETNAMESE_CHARSET, Vietnamese, 1258

Windows-1258

874 THAI_CHARSET, Thai, Windows-874 874

1361 JOHAB_CHARSET, Johab (Korean), 1361

Windows-1361

932 SHIFTJIS_CHARSET, Japanese, Windows- 932

CCSID932 932, shift_jis,x-sjis, ms_Kanji, cs, ShiftJIS
sjis-s IBM CCSID 932 Mixed including 1880 UDC
pc-sjis
cp932

ksc HANGUL_CHARSET, Korean, Korean 949

KS5601 (Wansung) KS C-5601-1987 Windows-949
cp949
57356

gb GB2312_CHARSET, Windows-936 Chinese 936

GB2312-80 (People's Republic of China, Singapore),
cp936 Simplified Chinese Microsoft Windows

big5 CHINESEBIG5_CHARSET, Windows-950, 950

Big-5 Traditional Chinese MS Windows Code Page
cp950 950, Chinese (Hong Kong SAR, China
57352 Taiwan)
(2 of 2)

Global Language Support C-9

Partially Supported WTK Character Sets

Partially Supported WTK Character Sets

The following table lists character sets that Four J’s BDL can use, but for which
Windows does not provide support for all characters. If you use any of these character
sets, you will find some characters are missing when you type the complete character
set. When possible, use the fully supported WTK character sets.

Microsoft Code
Code Set Character Set Name or Alias Page ID

819 IBM CCSID 819, C locale, POSIX Locale iso- 1252

ASCII 8859-1, us-ascii, standard ascii, latin1 ibm819,
C iso-ir-6,ANSI_X3
8859-1
Latin-1

912 iso-8859-1,iso-ir-101, ibm912, IBM CCSID 1250

8859-2 912
Latin-2

813 IBM CCSID 813, iso-8859-7, ibm813 1253

8859-7
Latin-Greek

916 IBM CCSID 916, ibm916, iso-8859-8 1255

8859-8
Latin-Hebrew

920 IBM CCSID 920, ibm920, iso-8859-9 1254

8859-9
Latin-5

1089 IBM CCSID 1089, iso-8859-6, iso-ir-127 1256

8859-6
Latin-Arabic
iso-ir-127
ASMO-708

57390 iso-8859-13 1257

8859-13
Latin-Baltic

C-10 Four J’s Business Development Language User Guide

Partially Supported WTK Character Sets

Setting the CLIENT_LOCALE Variable

Use the values in the table to correctly set the CLIENT_LOCALE variable. The
variable is created using the following syntax.
CLIENT_LOCALE= language_territory.codeSet

For example:
fr_ca.1252

The Code Set column in the following table lists the synonyms that can be used in the
CLIENT_LOCALE variable.

Important: For more information on setting the CLIENT_LOCALE variable, refer

to the “Informix Guide to GLS Functionality.”

Default Character Set

The Latin reference to Windows code pages denotes what is also called the Roman
alphabet in U.S. English. In any locale, Four J’s BDL requires at least one font that
supports the code set if the application needs to produce output to the screen or to a
report.

The default value on a UNIX computer is iso8859-1. This character set is not fully
supported. You should set CLIENT_LOCALE to en_us.1252 if you want complete
support for this character set.

For example:
CLIENT_LOCALE=en_us.1252
unset DB_LOCALE
(default value)

CLIENT_LOCALE=cs_cz.cp1250
DB_LOCALE=cs_cz.8859-2

CLIENT_LOCALE=ja_jp.sjis-s
DB_LOCALE=ja_jp.ujis

CLIENT_LOCALE=ko_kr.ksc
DB_LOCALE=ko_kr.ksc

CLIENT_LOCALE=ja_jp.sjis-s
DB_LOCALE=ja_jp.unicode

Global Language Support C-11

Internationalization and Localization

Internationalization and Localization

The terms internationalization and localization are near antonyms, but they both
describe activities that are critical for applications that will be deployed in more than
one locale. The first term, internationalization, refers to the work of analysts and
developers who must design and write code that is generalized for different cultural
contexts. The second term, localization, refers to the work of developers and trans-
lators who must adapt an internationalized application to the specific needs of a given
linguistic or cultural setting.

Internationalization is the process of making software applications easily adaptable

to different cultural and language environments.

Internationalization features support non-ASCII characters in character string values,

and adaptable number, time, and currency formats. Internationalization also implies
the ability to switch runtime environments from one language to another. Internation-
alization removes the need to recompile source code for a specific natural language
or cultural environment.

A fully-internationalized application can run in different cultural environments with

minimal adjustments, in some instances by simply exchanging language-specific
files and setting up the operating environment.

An internationalized application must support the use of extended ASCII code sets.
The default environment for 4GL is based on the ASCII code set of 128 characters.
Each of these encoded values (or code points) requires seven bits of a byte to store
each of the values 0 through 127, representing the letters, digits, punctuation, and
other logical characters of ASCII. Because each ASCII character can be stored within
a single byte, ASCII is called a single-byte character set. All other character sets that
4GL can support must include ASCII as a subset.

An internationalized application should, at a minimum, be 8-bit clean. A program,

GUI, or operating system is referred to as “8-bit clean” if it allows the high-order bit
of a character code to take on a value of 1. 4GL applications are 8-bit clean, and
therefore support the use of extended ASCII character sets, such as Windows code
pages or ISO 8859 character sets.

Localization is the process of translating and adapting an internationalized product to

specific language and cultural environments.

C-12 Four J’s Business Development Language User Guide

Global Language Support Terms

Localization usually involves setting the appropriate number, time, and currency
formats for the intended country, as well as creating a translation of the runtime user
interface (including help and error messages, prompts, menus, and reports).

You can reduce the cost and effort of localization if the application is designed with
international requirements in mind. This release of 4GL supports localization in
several areas:

• Entry, display, and editing of non-English characters

• References to SQL identifiers containing non-English characters
• Collation of strings containing non-English symbols
• Non-English formats for number, currency, and time values

For basic GLS concepts and for details of how Informix database servers and the
INFORMIX-ESQL/C product implement GLS, see the Informix Guide to GLS
Functionality.

Global Language Support Terms

Global language support (GLS) refers to the set of features that makes it possible to
develop user interfaces and other parts of an application so that they can use non-
Roman alphabets, diacritical marks, and so on. In order to understand the require-
ments of GLS, you will need to become familiar with the terms described in this
section.

Code Sets and Logical Characters

For a given language, the code set specifies a one-to-one correspondence between
each logical element (called a logical character, or a code point) of the character set,
and the bit patterns that uniquely encode that character. In U.S. English, for example,
the ASCII characters constitute a code set.

Code sets are based on logical characters, independent of the font that a display
device uses to represent a given character. The size or font in which 4GL displays a
given character is determined by factors independent of the code set. (But if you
select, for example, a font that includes no representation of the Chinese character for
star, then only whitespace will be displayed for that character until you specify a font
that supports it.)

Global Language Support C-13

Collation Order

Collation Order
Collation order is the sequence in which character strings are sorted. Database
servers can support collation in either code-set order (the sequence of code points) or
localized order (some other predefined sequence). See the Informix Guide to GLS
Functionality for details of localized collation.

4GL supports only code-set order. The database server, rather than 4GL, must do the
sorting if you require localized collation of data values in NCHAR or NVARCHAR
columns of the database. (You can write collation functions, but 4GL relational
operators always use the code-set order.)

Single-Byte and Multibyte Characters

Most alphabet-based languages, such as English, Greek, and Tagalog, require no
more than the 256 different code points that a single byte can represent. This
simplifies aspects of processing character data in those languages; for example, the
number of bytes of storage that an ASCII character string requires has a linear
relationship to the number of characters in the string.

In non-alphabetic languages, however, the number of different characters can be

much greater than 256. Languages like Chinese, Japanese, and Korean include
thousands of different characters, and typically require more than one byte to store a
given logical character. Characters that occupy two or more bytes of storage are
called multibyte characters.

C-14 Four J’s Business Development Language User Guide

Locales

Locales
For 4GL (and for Informix database servers and connectivity products), a locale is a
set of files that specify the linguistic and cultural conventions that the user expects to
see when the application runs. A locale can specify:

• The name of the code set

• The collation order for character-string data
• Culture-specific display formats for other data types
• The correspondence between uppercase and lowercase letters
• Determination of which characters are printable and which are nonprintable

The Informix Guide to GLS Functionality provides details of formats for number,
currency, and time values. If no locale is specified, then default values are for U.S.
English, which is the en_us.8859-1 locale on UNIX systems, or Windows code page
1252. For deployment, 4GL is also delivered with the locale en_us.1252@dict,
which corresponds to that Windows code page.

The locale en_us.1252@dict allows you to compile and run programs that contain
non-English characters from any single-byte language, but the default data formats
are those of U.S. English. Alternatively, you can use the Setnet32 utility to specify
some nondefault locale, such as one of those listed in “Locales Supported by 4GL”
on page C-21.

Global Language Support

GLS is a set of features that enable you to create localized applications for languages
other than U.S. English and for country-specific cultural issues, including the
localized representation of dates, currency values, and numbers. 4GL supports the
entry, retrieval, and display of multibyte characters in some East Asian languages,
such as Japanese and Chinese.

Global Language Support C-15

Native Language Support

The following GLS- enabled built-in functions or operators have been modified to
provide support for non-English locales. Some can accept multibyte characters
as arguments or operands, or can return values that include multibyte characters.

• CLIPPED operator
• DOWNSHIFT( )
• FGL_GETENV( )
• FGL_KEYVAL( )
• LENGTH( )
• Substring ( [ ] ) operator
• UPSHIFT( )
• WORDWRAP operator

See the INFORMIX-4GL Reference Manual for the syntax and semantics of these built-
in functions and operators. (Besides these, certain other built-in functions and
operators of 4GL can also process or return multibyte values.)

Native Language Support

The GLS capability of 4GL is not a logical superset of native language support (NLS)
as that term is used by Informix. An Informix NLS server is one that recognizes the
NCHAR and NVARCHAR data types. Such servers can communicate with client
applications in single-byte locales.

4GL supports Informix NLS servers at the implicit level of compliance, through
INFORMIX-NET and through INFORMIX-ESQL/C. The 4GL language does not
recognize NCHAR or NVARCHAR data types, but such values from the database
server are automatically converted to CHAR and VARCHAR values, and 4GL can use
CHAR and VARCHAR values to update NCHAR and NVARCHAR columns, provided
that an operating-system locale exists in the GLS directory for the NLS locale.

C-16 Four J’s Business Development Language User Guide

Non-GLS Components of This Release

The DBNLS value that is set on the client system running 4GL is passed to the
database server, but any LC_COLLATE value from the client is ignored. (Collation
by the 4GL application is based on the code-set order, not on LC_COLLATE, but the
database server can perform localized collation of NCHAR or NVARCHAR column
values, based on the LC_COLLATE setting.)

The COLLCHAR environment variable is not required to enable NLS; on the

contrary, 4GL requires that COLLCHAR not be set. If you have COLLCHAR set to
1, you must reset it to NULL. For more information about DBNLS, COLLCHAR, and
LC_COLLATE, see the Informix Guide to GLS Functionality.

Non-GLS Components of This Release

Not all components of 4GL provide GLS. This section identifies components of 4GL
that support only single-byte locales that do not require bidirectional text processing.

The absence of GLS does not imply that these features are unavailable in non-English
locales. It does imply, however, a restriction to locales that require only single-byte
code sets and left-to-right text processing.

Installation in Non-English Locales

This section identifies the general requirements for installation of 4GL in non-English
locales. Because non-English refers to all locales other than en_us.8859-1 (for UNIX)
or en_us.1252@dict (for Windows), most locales of the English-speaking world are
non-English in this context, as are the locales of most of the rest of the world.

The directory structure of Informix GLS products is shown in Figure C-2.

Global Language Support C-17

Installation in Non-English Locales

Figure C-2
*.cv Directory
cv9 Structure of GLS
Products
*.cvo

*.cm
gls cm3
*.cm
*.lc
en_us
lc11
*.lco
---
en_us 0333 *.iem
msg
---
$INFORMIXDIR etc (similar to msg

forms (similar to msg

release (similar to msg

en_us 0333 *
sql
demo
---
---

C-18 Four J’s Business Development Language User Guide

Requirements for International Application Development

Requirements for International Application

Development
The following requirements must be met to develop a 4GL application that is fully
adapted to a language or to a country:

• The targeted hardware platform and operating system need to support the
desired language and country combination.
The operating-system environment on both the client platform and the
server platform might require special versions to support the entry, manip-
ulation, and display of non-English data.
• The Informix products need to support the language. Informix products are
8-bit clean and allow entry, manipulation, and display of most European and
Asian language data.
• Error messages generated by 4GL and the database server should be
available in a localized version, so that only local languages appear in the
runtime environment.
• All parts of the user interface created by the application developer (such as
menus, prompts, error messages, and help) should be translated into the
target language.

In many cases, the last three of these four requirements can be met by using an
Informix language supplement. Your Informix sales representative can advise you
regarding the availability of language supplements, of localized versions of
Windows, and of database servers that are compatible with 4GL.

Global Language Support C-19

Language Supplements

Language Supplements
Use of 4GL with some non-English languages might require an Informix language
supplement specific to the conventions of the country or language. Language supple-
ments are currently required, for example, for Informix database servers to support
each of the following East Asian languages.

Country or Language Informix Language Supplement

People’s Republic of China Language Supplement ZHCN 7.20

Taiwanese Language Supplement ZHTW 7.20

Japanese Language Supplement JA 7.20

Korean Language Supplement KO 7.20

Thai (simplified) Language Supplement TH 7.20

Language supplements for these East Asian languages include locale files,
translated message files, and translated menu files. Localized versions of 4GL for
East Asian locales (for example, Japanese 4GL) will include the relevant files. See the
release notes for additional information.

A corresponding International Language Supplement includes locale files and code-

set conversion files for most European languages. Because most of these files are
included with the INFORMIX-NET (7.2) connectivity software that is provided with
4GL, this supplement need not be purchased by 4GL customers unless the required
locale is not included with 4GL.

When the Informix database server is installed in locales based on non-English

European languages, both the default (English) database server and the International
Language Supplement must be installed.

When 4GL is installed, the locale files must also be installed. Contact your Informix
sales office for information regarding current support for specific locales.

C-20 Four J’s Business Development Language User Guide

Locales Supported by 4GL

Locales Supported by 4GL

A locale is the part of the processing environment that defines conventions for
a given language or culture, such as formatting time and money values, and classi-
fying, converting, and collating characters. The Informix GLS locale definition is
similar to the X/Open CAE Specification.

Code sets that WTK 4GL supports include those listed in the following table.

Country or Language Windows Code Page

People’s Republic of China 936 (also known as GB 2312-80)

Taiwanese 950 (also known as Big-5)

Japanese 932 (also known as Shift-JIS)

Korean 949 (also known as KSC 5601)

Eastern European (Latin) 1250

Eastern European (Cyrillic) 1251

Western European (Latin) 1252

Greek 1253

Turkish 1254

Here Latin in reference to Windows code pages 1250 and 1252 denotes what is also
called the Roman alphabet in U.S. English. In any locale, 4GL requires at least one
font that supports the code set, if the application needs to produce output to the screen
or to a report.

4GL provides limited support for the Thai language through code set th_th.thai620,
with Language Supplement TH 7.20, for non-composite Thai characters. ( 4GL does
not support composite Thai characters.)

Global Language Support C-21

Locales Supported by 4GL

Client Locales and Server Locales

The locale of the system on which the 4GL application is running is called the client
locale. For an application that is partitioned through 4GL, this refers to the locale of
the application server and of the display server. The locale of the database server is
called the server locale. “Handling Code-Set Conversion” on page C-49 describes
special procedures that might be required if the client locale and the server locale are
not identical.

Setting Environment Variables for Specific Locales

4GL requires that environment variables be set correctly on UNIX systems that
support the database server or 4GL applications that support application server and
display server partitions. For details about setting environment variables on UNIX
systems for GLS, see the Informix Guide to GLS Functionality. See also “Configuring
the Language Environment” on page C-36 of for additional information about setting
environment variables.

To set environment variables on Windows 9x systems, you set most environment

variables in the Windows 9x or NT 4.0 registry by using the Setnet32 utility.

See the Informix Guide to GLS Functionality for an example of non-English locale
files.

C-22 Four J’s Business Development Language User Guide

Requirements for All Locales

Requirements for All Locales

This section outlines the steps that are needed to create localized 4GL applications:

1. Set up the development environment.

The system administration tools that you use must belong to the database
server. You can use a UNIX terminal or a local terminal-emulation program
on Windows (provided that it supports the local code set).
2. Write the code.
Filenames (source and compiled) must contain only English characters.
3. Compile and debug the code.
The 4GL compiler can compile and link the components of the application.
The Message Compiler can compile non-English text, so that runtime mes-
sages can be displayed in the local language. The user interface of the
Message Compiler is in English.
Any Windows help requires the Windows Help Compiler.
The INFORMIX-4GL Interactive Debugger is not GLS-enabled. (The Four
J’s BDL Debugger has sufficient GLS capability to display non-English
characters from the client locale.)
4. Deploy the code.
Deployment is relatively unrestricted. Applications that can be created
through the steps outlined here are localized applications for a specific
locale, and therefore are not internationalized. (That is, they should not be
used in another locale that requires, for example, a different code set from
that of the message files.)

Global Language Support C-23

The 4GL Compilers

The 4GL Compilers

The compilers have limited GLS capability, as the sections that follow describe.

The 4GL Character Set

4GL keywords, identifiers, delimiters, and special symbols in source code are
restricted to the same ASCII characters described in the INFORMIX-4GL Reference
Manual. Additional printable characters from the client locale, however, are valid
within source code files in the following contexts only:

• Within comments
• Within 4GL identifiers
• Within certain SQL identifiers (as listed in the table in “SQL and 4GL
Identifiers” on page C-25)
• Within expressions where character-string literals are valid

In non-English locales, 4GL identifiers can include non-ASCII characters in identi-

fiers if those characters are defined in the code set of the locale that
CLIENT_LOCALE specifies. In multibyte East Asian locales that support languages
whose written form is not alphabet-based, a 4GL identifier need not begin with a
letter, but the storage length cannot exceed 50 bytes. (A Chinese identifier, for
example, that contains 50 logical characters would exceed this limit if any logical
character in the identifier required more than one byte of storage.)

Non-English characters in other contexts, or characters that the client locale does not
support, will generally cause compilation errors.

At runtime, the user can enter, edit, and display valid characters from the code set of
the client locale. Whether a given character from a non-English code set is printable
or nonprintable depends on the client locale.
Values that include non-English characters can be passed between a 4GL application
and the database server, if the client and server systems have the same locale. If the
locales are different, data can still be transferred between the 4GL client and the
database server, provided that the client locale includes appropriate code-set
conversion tables. See “Configuring the Language Environment” on page C-36 or the
Informix Guide to GLS Functionality for information about establishing a locale and
about code-set conversion between locales. See also “Handling Code-Set
Conversion” on page C-49.

C-24 Four J’s Business Development Language User Guide

The 4GL Compilers

Non-English Characters
The following features of the 4GL compiler are GLS-enabled to support non-English
characters that are valid in the client locale:

• Names of identifiers
• Values of CHAR and VARCHAR variables and formal arguments
• Characters within TEXT blobs
• Message text, quoted strings, and values returned by functions
• Text within comments, forms, menus, and output from reports

Named 4GL program entities include variables, functions, cursors, formal arguments,
labels, reports, and prepared objects. 4GL has a limit of 50 bytes on the lengths of
these names.

SQL and 4GL Identifiers

SQL identifiers are the names of database entities, such as table and column names,
indexes, and constraints. The first character must be an alphabetic character, as
defined by the locale, or an underscore (= ASCII 95) symbol. You can use alphanu-
meric characters and underscores ( _ ) for the rest of the SQL identifier. Most SQL
identifiers can be up to 18 bytes in length. What characters are valid in SQL identifiers
depends on the locale of the database server. Neither single-byte nor multibyte
whitespace characters can appear in SQL identifiers.

SE For INFORMIX-SE database servers, whether non-English characters are permitted in

the names of databases, tables, or log files depends on whether the operating system
permits such characters in filenames. ♦

Global Language Support C-25

The 4GL Compilers

The user interface of the 4GL compiler is in English. If edit fields contain multibyte
characters, there is no checking, and the results might be unpredictable. Embedded
SQL statements can include valid non-English identifiers for some database
entities.The following tables summarize the instances where non-English characters
are valid as identifiers within 4GL source code modules. The first table lists SQL
identifiers.

SQL Identifier Allow Non-English Characters

Column name Yes

Constraint name Yes

Database name Yes (Operating System limitations on INFORMIX-SE)

Index name Yes

Log filename Yes (Operating System limitations on INFORMIX-SE)

Stored procedure name Yes

Synonym Yes

Table name Yes (Operating System limitations on INFORMIX-SE)

View name Yes

The following 4GL identifiers allow non-English characters.

4GL Identifier Allow Non-English Characters?

Variable name Yes

Cursor name Yes

Filename or pathname No

Formal argument name Yes

Function or report name Yes

Prepared statement name Yes

Statement label Yes

C-26 Four J’s Business Development Language User Guide

The 4GL Compilers

Input and output filenames for the 4GL compiler cannot be localized. Only ASCII
characters are valid in input and output pathnames or filenames. (If support for
uppercase ASCII letters is required, specify en_us.1252@dict as the locale at compile
time. Uppercase letters are not defined in en_us.1252.)

Collation Sequence
The collation (sorting) sequence in 4GL statements is implied by the code-set order
in the files that define the client locale. (Any collating that is specified by the
LC_COLLATE value of the client locale is ignored.) Collation in SQL operations
(where the database server uses its own collation sequence) depends on the data type
and on the server locale (which can specify a localized order of collation). It is
possible for the 4GL application and the database server to use a different collating
sequence, or for a 4GL application to connect to two or more servers that use different
collating sequences. The collation sequence can affect the value of Boolean expres-
sions that use relational operators and the sorted order of rows in queries and in
reports.

Locale Restrictions
The compiler requires the en_us.0333 locale. It accepts as input any source file
containing data values in the format of the client locale. The compiler can generate
binaries or P-code files with client-locale text strings. The runtime locale of a 4GL
program must be the same as its compile-time locale.

As a convenience to the developer, 4GL adds a field in P-code header files to specify
the locale in which the files were compiled but does not compare these locales.

The Forms Compiler

The fglform forms compiler can process form specifications that include non-
English characters that are valid in the client locale. It can also produce compiled
forms that can display characters from the client locale, and that can accept such
characters in input from the user.

The Message Compiler

The fglmkmsg message compiler has a user interface in English but can compile
non-English text into runtime messages in the local language.

Global Language Support C-27

East Asian Language Support

On-Line Help
Help for 4GL applications in non-English locales requires the native Windows Help
facility.

East Asian Language Support

4GL can create applications for Asian languages that use multibyte code sets. This
support is only available when 4GL applications are developed and run under a
multibyte version of Microsoft Windows or UNIX.

4GL supports the following features in multibyte locales:

• Menu items, identifiers, and text labels in the native language

• Features to avoid the creation of partial characters
• Non-English data within 4GL applications
• Cultural conventions, including the representation of date, time, currency,
numeric values, and localized collation
• Kinsoku processing for Japanese language text with WORDWRAP
• Icon modification without changing the 4GL application binary
• Text geometry that adjusts automatically to meet localization needs
• Application comparisons that adopt the comparison rules and collating
sequence that the locale defines implicitly (SQL comparison and collation
depend on the database server.)

This version of 4GL does not support composite characters, such as are required in
code sets that support the Thai language.

4GL comments and character string values can include multibyte characters that are
supported by the client locale in contexts like these:

• Character expressions and multiple-value character expressions

• Literal values within quoted strings
• Variables, formal arguments, and returned values of CHAR, VARCHAR, and
TEXT data types

C-28 Four J’s Business Development Language User Guide

East Asian Language Support

Multibyte characters can also appear in 4GL source code (or in user-defined query
criteria) that specifies the SQL identifier of any of the database objects listed in the
table on “SQL and 4GL Identifiers” on page C-25. 4GL does not, however, support
multibyte characters as currency symbols or as separators in display formats that
DBDATE or DBFORMAT specifies.

Logical Characters
Within a single-byte locale, every character of data within character-string values
requires only a single byte of memory storage, and a single character position for
display by a character-mode device.

This simple one-to-one relationship in character-string operations between data

characters, display width, and storage requirements does not exist in East Asian
locales that support multibyte characters. In such locales, a single logical character
might correspond to a single byte or to two or more bytes. In such locales, it becomes
necessary to distinguish among the logical characters within a string, the display
width that the corresponding glyph occupies in a display or in report output, and the
number of bytes of memory storage that must be allocated to hold the string.

In locales that support multibyte characters, some built-in functions and operators
that process string values operate on logical characters, rather than on bytes. For code
sets that use multibyte characters, this modifies the byte-based behavior of several
features in 4GL. A single logical character can occupy one or more character
positions in a screen display or in output of a report, and requires at least one byte of
storage, and possibly more than one.

Declaring the CHAR or VARCHAR data types of variables, formal arguments, and
returned values is byte-based. Runtime processing of some character strings,
however, is done on a logical character basis in multibyte locales.

Partial Characters
The most important motivation for distinguishing between logical characters and
their component bytes is the need to avoid partial characters. These are fragments of
multibyte characters. Entering partial characters into the database implies corruption
of the database, and risks malfunction of the database server.

Partial characters are created when a multibyte character is truncated or split up in

such a manner that the original sequence of bytes is not retained. Partial characters
can be created during operations like the following:

Global Language Support C-29

East Asian Language Support

• Substring operations
• INSERT and UPDATE operations of SQL
• Word wrapping in reports and screen displays
• Buffer to buffer copy

4GL does not allow partial characters and handles them as follows:

• Replaces truncated multibyte characters by single-byte whitespaces

• Wraps words in a way that ensures that no partial characters are created in
reports and screen displays
• Performs code-set conversion in a way that ensures that no partial characters
are created

For example, suppose that the following SELECT statement of SQL:

SELECT col1[3,5] FROM tab1

retrieved three data values from col1 (where col1 is a CHAR, NCHAR, NVARCHAR,
or VARCHAR column); here the first line is not a data value but indicates the
alignment of bytes within the substrings:
AA2BB2AA becomes "s1Bs1"
ABA2C2AA becomes "A2s1"
A2B2CABC becomes "B2C"

Here the notation s1 denotes a single-byte whitespace. Any uppercase letter followed
by a superscript ( 2 ) means an East Asian character with multibyte storage width; for
simplicity, this example assumes a 2-byte storage requirement for the multibyte
characters. In the first example, the A2 would become a partial character in the
substring, so it is replaced by a single-byte whitespace. In the same substring, the B2
would lose its trailing byte, so a similar replacement takes place.

C-30 Four J’s Business Development Language User Guide

General Guidelines

General Guidelines
This section lists the issues that you need to consider when writing and translating
applications.

Internationalization Guidelines
To make a 4GL application world-ready, keep the following guidelines in mind:

• Do not assume that application users are English-speaking or will accept

any pre-set business rules or formats.
• Use code libraries wherever possible. This centralizes common code and
makes changes and maintenance easier when developing for international
markets.
Specific programming areas that might require special attention (and that
are treated in detail in the Informix Guide to GLS Functionality) include:
•• character-string display, entry, storage, retrieval, and processing.
•• formats for literal date, time, currency, and numeric values.
•• code-set conversion between client and server.
• In all windows that will appear in more than one language, consider differ-
ences in word length among languages when you are designing the window
and its graphical objects.
• Allow space for the expansion of user message strings. Brief English strings
such as Popup can double in size as a result of translation. On average, you
can expect a 30 percent increase in the size of messages.
• When designing windows, remember that names, addresses, dates, times,
and telephone numbers have different formats in different countries.
• When possible, use picture buttons instead of buttons with titles.
• Consider that measurement systems can also differ. Most countries outside
the U.S. express quantities using the metric system. For example, liters,
centimeters, and kilometers instead of quarts, inches, and miles.

Global Language Support C-31

Internationalization Guidelines

• Make sure that all screens, menus, user messages, reports, help facilities,
and application parameters (such as holidays, bank years, formulas) that
were developed with Informix tools for the application are either table-
driven or are controlled by text files or environment variables that are easy
to modify. This issue is discussed later in this appendix.
• Avoid embedding any messages, prompts, or elements of the user interface
into the source code of the program. Ideally, all user interface elements can
be switched dynamically by referencing a different set of translated files.
• Consider different keyboard layouts. A character (such as “/”) that is easily
accessible on an ASCII keyboard might require several keystrokes in the
standard keyboard of some other country.
• Consider creating a configuration utility to deal with different font types.
Some applications that will be deployed in several different countries might
need to load different fonts to accommodate specific national characters.
Because these fonts are often supplied by third parties, you might not be able
to predict the font names when you develop the application. In this case, you
can use the default font names and provide a configuration utility that allows
the user to specify the font name before running the application.
• Consider differences in paper size when designing reports. Most countries
outside the U.S. use the ISO Standard A4 paper size, which is 21 by 29.7
centimeters, slightly longer and narrower than the American standard 8.5 by
11 inches.
• Avoid fragmentation of messages or potentially ambiguous key
or command words. Avoid determining variable portions of a message at
runtime; for example, the differing syntax of other languages can make the
order in which your functions return parameters an obstacle to correct
translation.
• Wherever possible, avoid abbreviations, acronyms, contractions, and slang.
• Place comments around any string pertaining to the user interface
to facilitate localization.
• Use localized error messages and help files. The message compiler utility
that is provided with 4GL enables you to create customized help files as well
as a localized version of the 4GL runtime message file. (This is the
4glusr.msg file in the msg directory.) Internationalizing messages is further
discussed in “Localizing Prompts and Messages” on page C-47.
• You can handle reports (which are 4GL programs) in the same way that you
internationalize the rest of your 4GL source code.

C-32 Four J’s Business Development Language User Guide

Localization Guidelines

If your database server and ESQL/C API are Version 6.0 or later, you might be able
to take advantage of Native Language Support (NLS) functionality, even though 4GL
provides only implicit support for NLS. For more information, see the Informix Guide
to SQL: Reference.

Localization Guidelines
Localization refers to the actual process of adapting the application to the cultural
environment of end users. This process often involves translation of the user interface
and user documentation and can be quite time consuming and costly. Here are some
guidelines to follow:

• Consult the native operating-system internationalization guide.

Most platforms provide documentation on internationalization. This mate-
rial might help you determine which date, time, and money formats are
appropriate for the target language and culture.
For more information about internationalization and Windows, see “Inter-
national Applications” in the Microsoft Windows Programmer’s For more
information about internationalizing Informix products in the UNIX envi-
ronment, see the Informix Guide to SQL: Reference.
For information about the terms and constructs of GLS technology, see the
Informix Guide to GLS Functionality.
• Make sure the targeted hardware, operating-system environments, and
Informix product versions of your applications can support the desired
language and culture.
• Find out if the runtime environment of 4GL and of the database server is
currently available in the target language.
For example, the 4GL runtime environment (and the Informix Dynamic
Server administrator’s environment) is usually translated into several lan-
guages, including French, German, Spanish, Russian, and Japanese.
• Keep a glossary of all strings and keywords in a database or text file.
This glossary will make it easier to see which messages are duplicated
throughout the source code. The glossary will also increase the consistency
of terms and language in the user interface throughout the application. Once
the glossary is created for one language, it can be used for product updates
and additional localizations.

Global Language Support C-33

Localization Methodology Overview

• Create a mechanism that allows a glossary to drive the definition of the user
interface.
This can be particularly useful if you expect to localize the application often.
A translator can edit the glossary without having to understand the source
code of the application. Your tool can then create the user interface from the
translated glossary, and the translator can focus on making cosmetic
enhancements to the translation (such as positioning the messages appropri-
ately) and correcting minor errors.
• Consider creating a checklist of those user interface elements in your appli-
cation that should be externalized into text files from the source code, and
therefore from the compiled portion of the program. These text files can
then be modified even after the program is compiled. Externalize the
following elements:
•• Menus
•• Forms
•• Messages
•• Labels
•• Help (.msg) text
•• Numeric, date, time, and money formats
•• Report names
• Consider retaining a professional translator for some or all of this process.
A faulty translation is costly. You can spend a great deal of time and money
correcting errors in your localized product. And if you do not correct the
problems, your users will be dissatisfied with your application.

Localization Methodology Overview

This section lists the elements of an application and indicates some ways in which
each can be localized. This overview, while not comprehensive, illustrates how to
approach a project of this nature. The rest of this appendix expands on the approaches
listed here.

For many of the application elements discussed in this section, the two methods of
localization are the table-based approach and the file-based approach. The table-
based approach involves obtaining translation information from a database using
SQL queries. The file-based approach involves retrieving the values of the variables
from a text file.

C-34 Four J’s Business Development Language User Guide

Localization Methodology Overview

Application Help and Error Messages

The following methods are available for localizing application help and error
messages.

Table-Based Localization of Messages

To use this method, you need to verify the availability of tables. It often also requires
the hard coding of defaults in case the database cannot be accessed.

File-Based Localization of Messages

This method uses the message compiler utility to create help and error message files.
For more information, see “Localizing Prompts and Messages” on page C-47.

Date, Time, and Currency Formats

To localize formats for dates, time, and money values, set the Informix environment
variables DBDATE, DBFORMAT, and DBMONEY. Formatting conventions of some
East Asian locales require that the GL_DATE environment variable be set.

Informix System Error Messages

The following methods are available for localizing Informix system messages and
error messages.

Informix Translation
Informix provides error message translation for a variety of languages. You can use
the DBLANG environment variable to point to a message directory containing trans-
lated messages. Contact your local Informix sales office for a list of available
language translations.

Customized System Error Message Files

If no Informix translation of the error messages is available, and if the source code of
error message files is delivered with the product, you can localize the message source
files using the message compiler utility. For more information, see “Localizing
Prompts and Messages” on page C-47.

Global Language Support C-35

Configuring the Language Environment

Code-Set Conversion
The method available depends on whether you are using UNIX or Windows:

• For UNIX systems, set the DBAPICODE environment variable.

• For Windows systems that use INFORMIX-NET with Four J’s BDL, set the
CLIENT_LOCALE and DB_LOCALE entries in the registry.

For details, see “Handling Code-Set Conversion” on page C-49.

Configuring the Language Environment

Environment settings that affect the language environment exist both in your 4GL
environment and in your system environment. Using the GLS features of 4GL with
Informix database servers involves several compatibility issues:

• The English servers create English databases with ASCII data. For these, the
4GL program must access the servers with DB_LOCALE set to en_us.8859-
1.
• The 5.x ALS versions of Informix servers can use variables such
as DBCODESET and DBCSOVERRIDE as substitutes for DB_LOCALE and
DBCONNECT, respectively. These environment variables need to be set by
using Setnet32.
• The 5.x ALS versions use DBASCIIBC to emulate the 4.x ASCII servers.
This environment variable should be set in the registry, if such behavior
is desired.
• The SERVER_LOCALE environment variable is set on the database server,
not on the 4GL client. This specifies the locale that the database server uses
to read or write operating-system files. If this is not set, the default is U.S.
English (en_us.8859-1).

If no setting is specified, the 4GL application uses an English locale. But the registry
sets everything to the local language, code set, or locale, so the practical default is for
applications to use the local locale.

C-36 Four J’s Business Development Language User Guide

Configuring the Language Environment

The non-internationalized portions of the product are initialized with the default
(U.S. English) locale. That is, both CLIENT_LOCALE (en_us.1252) and
DB_LOCALE (en_us.8859-1) are set to English. This initialization is necessary
because many common functions are shared between the internationalized and non-
internationalized components.

Important: Except for DBFORMAT, all the environment variables that are
described in the sections that follow apply to Informix database servers.

Global Language Support C-37

Environment Variables That Support GLS

Consider also the following points:

• The application cannot support connections to different databases with

different locales concurrently; for example, in extended joins.
• The environment variables discussed here deal with the environment
DB_LOCALE that is passed to the server.
• CLIENT_LOCALE cannot be changed dynamically during execution.
• The previous point has one exception: the CLIENT_LOCALE can always be
set to English (because English is a subset of all locales).

When connecting to a GLS, NLS, or ALS (Asian Language Support) database, the
DB_LOCALE code set should match the DB_LOCALE code set of the database.
Otherwise, data corruption can occur, because no validation of code-set compatibility
is performed by the server. An ALS server can refuse the connection when the code
sets do not match, but an NLS server cannot.

Environment Variables That Support GLS

This section examines the environment variables that support the GLS capabilities of
4GL, including the following 4GL environment variables:

• DBDATE defines date display formats.

• DBMONEY defines monetary display formats.
• DBFORMAT defines numeric and monetary display formats and has more
options than DBMONEY.

Four J’s Uninersal 4GL also supports the following GLS environment variables:

• DB_LOCALE is the locale of the database to which the application

is connected.
• CLIENT_LOCALE is the locale of the system that is executing the 4GL
application.
• DBLANG points to the directory for language-specific message files that an
Informix product uses, such as Informix error messages.
• GL_DATE defines date displays, including East Asian formats.
• SERVER_LOCALE is the locale of the database server for file I/O.

C-38 Four J’s Business Development Language User Guide

Environment Variables That Support GLS

4GL does not use DB_LOCALE directly; this variable, as well as DBLANG, is used
by the GLS version of INFORMIX-NET PC. See the Informix Guide to GLS Function-
ality for details on how DBLANG, DB_LOCALE, GL_DATE, are set.

Compatibility Issues
In order for 4GL to work with older Informix database servers (such as 5.x ALS), it is
necessary for these environment variables to be set in the Windows registry. This is
done by the GLS version of INFORMIX-NET PC. When the 4GL application accesses
an NLS database, appropriate NLS environment variables must be set in the registry
if NLS functionality is desired.

DBAPICODE
This environment variable specifies the name of a mapping file for peripheral devices
(for example, a keyboard, a display terminal, or a printer) whose character set is
different from that of the database server.

DB_LOCALE
This environment variable specifies the locale of the database to which the 4GL
component or application is connected. The only Informix databases that currently
support non-English languages exist in UNIX. Therefore, when the locales are non-
English, the localized 4GL application can only connect to these databases. The
format for setting DB_LOCALE is DB_LOCALE=<locale>.

Consider also the following points regarding DB_LOCALE:

• If the application uses this value to access a database, the locale of that
database must match the value specified in DB_LOCALE. If it does not
match, the database connection might be refused (unless DBCSOVERRIDE
is set to 1), depending on the server version.
• If a database is created, then this new database has the value specified by
DB_LOCALE.
• If DB_LOCALE is invalid, either because of wrong formatting or specifying
a locale that does not exist, then an error is issued.
• If the code set implied by DB_LOCALE cannot be converted to what
CLIENT_LOCALE implies, or vice versa, an error is issued.

Global Language Support C-39

Environment Variables That Support GLS

• If DB_LOCALE is not specified, there is no default value; in this case, the

GLS version of INFORMIX-NET PC behaves as if code-set conversion were
not needed.

CLIENT_LOCALE
This environment variable specifies the locale of the (input) source code and the
compiled code (to be generated). This is also the locale of the error files (if any) and
the intermediate files. The format of CLIENT_LOCALE is the same as that of
DB_LOCALE:

• The characters that reach the user interface (the non-ASCII characters) must
be in the CLIENT_LOCALE.
• If DB_LOCALE is invalid, either because of wrong formatting or specifying
a locale that does not exist, an error is issued.
• The DB_LOCALE and CLIENT_LOCALE settings need to be compatible,
meaning there should be proper code-set conversion tables between them.
Otherwise, an error is issued.
• If CLIENT_LOCALE is not set in the Windows client, then Windows code
page 1252 is the default.
• The CLIENT_LOCALE must match the environment of the user interface
(meaning that it should be compatible with the local version of Windows).
Otherwise, an error is issued.
• Collation by the 4GL application follows the code-set order
of CLIENT_LOCALE, except in SQL statements (where the database server
uses its own collation sequence). Any LC_COLLATE specification is
ignored.

C-40 Four J’s Business Development Language User Guide

Environment Variables That Support GLS

DBLANG
The value of DBLANG is used to complete the pathname to the directories that
contain the required message, help, and demo files. The format of DBLANG is the
same as that of DB_LOCALE:

• If DBLANG is not set, the value defaults to that of CLIENT_LOCALE.

• If DBLANG is invalid, then en_us.1252 is the default value. This case
occurs if DBLANG is improperly formatted, or if it points to a locale that
does not exist, or points to a locale that is incompatible with the version of
Windows on which the 4GL application is running.

See also the description of DBLANG in the Informix Guide to GLS Functionality.

DBDATE
The DBDATE environment variable has been modified to support era-based dates
(Japanese and Taiwanese). The days of the week and months of the year (in local
form) are stored in the locale files. If this environment variable is set, it might
override other means of specifying date formats.

DBMONEY
This environment variable has been modified to accept multibyte currency symbols.
4GL components that read the value of DBMONEY (or DBFORMAT) must be able to
correctly process multibyte characters as currency symbols. If DBMONEY is set, its
value might override other means of specifying currency formats.

DBFORMAT
This environment variable has been modified to accept multibyte currency symbols.
Unlike the version of DBFORMAT for English products, display of the decimal point
is optional, rather than mandatory, in 4GL. (Use of a comma as the DBFORMAT
decimal separator can produce errors or unpredictable results in SQL statements in
which 4GL variables are expanded to number values that are formatted with commas
as the decimal separator.)

If DBFORMAT is set, its value can override other means of specifying number or
monetary formats.

Global Language Support C-41

Environment Variables That Support GLS

The glfiles utility is described in the Informix Guide to GLS Functionality and is
packaged with INFORMIX-4GL and INFORMIX-SQL products. This utility allows you
to generate lists of the following files:

• GLS locales available in the system

• Informix code-set conversion files available
• Informix code-set files available

Default Values of GLS Environment Settings

Default values assumed by INFORMIX-4GL and INFORMIX-SQL products (which
differ from those of ALS environments) are described in this section.

The following table shows the values assumed by 4GL when you define only some of
the required values of locales.

(A value of ja-jp.ujis is assumed in the following example. CL means

CLIENT_LOCALE, and DL means DB_LOCALE.)

User Defined Values in Product

CL DL
Defined CL Value Defined DL Value CL Value DL Value

No -- No -- en_us.8859 en_us.8859

Yes ja_jp.ujis No -- ja_jp.ujis ja_jp.ujis

Yes ja_jp.ujis Yes ja_jp.ujis ja_jp.ujis ja_jp.ujis

No -- Yes ja_jp.ujis en_us.8859 ja_jp.ujis

If you do not set the DBLANG environment variable, it is set to the value of
CLIENT_LOCALE.

C-42 Four J’s Business Development Language User Guide

System Environment Variables

System Environment Variables

This section describes how you can query your system environment for language and
country variables.

Windows Environment Variables

To access the language environment variable programmatically, you can use any of
the following three approaches:

• Read the Language value directly from the [ResourceLocale] section of

the registry, specifically:
HKEY_CURRENT_USER\Control Panel\Desktop\ResourceLocale
This has a 32-bit numeric value called a locale ID, part of which defines the
language that is used in the Windows user interface. The numbers are
defined in WINNT.H.
For example, if ResourceLocale is set to 00000409, the 10 lower-order
bits 0000001001 ( = hexadecimal 009) represent English, the constant
LANG_ENGLISH in the winnt.h file. If the value is set to 00000401, then
001 represents Arabic (LANG_ARABIC).
(You can also read and modify this setting through the Control Panel.)
On Windows 9x and Windows NT, use the registry, rather than .ini files, but
.ini files are supported (so that you can install pre-Windows 9x programs).

Global Language Support C-43

System Environment Variables

Some of the language codes that Windows currently supports are listed in
the following table.

Code Language Code Language

ENU U.S. English FRC Canadian French

ENG U.K. English ISL Icelandic

DAN Danish ITA Italian

DEU German NLD Dutch

ESN Modern Spanish NOR Norwegian

ESP Castilian Spanish PTG Portuguese

FIN Finnish SVE Swedish

FRA French

For more information about internationalization and Windows, see the

Microsoft Windows Programmer’s Reference.
• Create an environment variable for the language, either with Setnet32, or,
for applications that are deployed on Windows 3.1 systems, in the
informix.ini file (by adding the variable and its setting to the
[ENVIRONMENT] section). Then use the built-in FGL_GETENV( ) function
of 4GL in your code. For example:
VARIABLE langStr CHAR(30)
LET langStr = FGL_GETENV("LANGUAGE")
Your program can now test for the value that you specified in LANGUAGE.

C-44 Four J’s Business Development Language User Guide

Storing Localization Information

You can develop your own language variable scheme. For example, the fol-
lowing three-letter codes identify a unique subdirectory that contains the
translation files appropriate for a particular language.

Subdirectory Language

eng English

fre French

ita Italian

spa Spanish

You might want to use this or the next approach if you need to control your
application’s language setting separately from that of other Windows
applications.
• Create your own .ini file and language variable, and have your application
read this file for the language setting.

UNIX Environment Variables

The value of the X/Open-defined LANG environment variable specifies the language
environment. No standardization of LANG locale values exists between systems.
Exact values to specify for locale variables are specific to the system and also depend
on which language supplements have been installed on the system.

To query programmatically for the language value, you can use the built-in
FGL_GETENV( ) function:

FGL_GETENV("LANG")

For more information about the LANG environment variable, see the Informix Guide
to SQL: Reference.

Storing Localization Information

This section describes the process involved in creating an application so that it can
read translation information, either from a file or from a database table at runtime.

Global Language Support C-45

File-Based Localization

File-Based Localization
You can store the translations of localized information in disk files and access them
at runtime as needed.

You can use subdirectories to store language-sensitive files so they can easily be
switched to create a new runtime environment. In the following example, the
filename is composed by reading the value of an environment variable (created by the
programmer) that specifies a Windows language subdirectory:
LET file001 = FGL_GETENV("LANGUAGE"), "\", "trans.4gl"
# Evaluates to "eng\trans.4gl" if LANGUAGE is "eng"
# Program reads the eng directory for copy of translation
#
# Evaluates to "ger\trans.4gl" if LANGUAGE is "ger"
# Program reads the ger directory for copy of translation
#
LET tranfile = file001

In the preceding example, change the backslash character to a forward slash (/) for
UNIX systems.

Table-Based Localization
Localization information can also be stored in database tables. This information can
be used when you initialize or run the application to change the value of variables that
define titles, menus, and other language or culturally sensitive elements of the user
interface. An advantage of the table-based approach is that it is highly portable
between systems.

Setting Up a Table
The following example shows one way that you might set up a table to store menu
options:
CREATE TABLE menu_elements(
option_language CHAR(3), #language ID code
option_number SMALLINT, # identifying number
option_text CHAR(80), # text
option_maxlen SMALLINT # maximum length of string
)

CREATE UNIQUE INDEX ix_menustr

ON menu_elements(option_language, option_number)

C-46 Four J’s Business Development Language User Guide

Localizing Prompts and Messages

Example data:
ENG150Cold Beer
FRE150Bière froide
GER150Kaltes Bier
SPA150Cerveza fría
ENG151Iced Tea
...

Querying the Table

A global variable that contains the language code of the application, which
corresponds to the value in the option_language column, can be set in the program
at startup. Each time a character string is needed, a function could be called that uses
the language and identifying number to query the table for the appropriate string:
LET lang = getLanguage()# returns 3 letter code
# from option_language column

Localizing Prompts and Messages

You can use the 4GL message compiler utility to create translated message files for
your application messages. These files, which usually have the extension .iem, run
very quickly.

Creating Message Files

For any natural language, follow these steps to create new language versions of the
messages and prompts that your application displays.

Global Language Support C-47

Localizing Prompts and Messages

To create new message files

1. With a text editor that can create flat files, create a source (.msg) file with
the following format:
.message-number
message-text
.message-number
message-text
For example:
.1000
Part not found.
.1001
Price must be a positive number.
.1002
Invalid format for phone number.
To translate the messages into another language, simply provide translated
versions for the message text, using the same format.
2. At the system prompt, invoke the message compiler utility
(fglmkmsg) by using a command of the following form:
fglmkmsg filename
The message compiler processes filename.msg and produces a compiled
message file that has the name filename.iem.
If you want the compiled message file to have a different name from the
source file, specify that filename as a final argument:
fglmkmsg source output

Accessing Message Files

To access the compiled message file from your application, you can write a function
that reads the messages from the compiled (.iem) file. For example, the calling
program includes logic to display a Part not found message in the following
pseudo-code:
DEFINE OK, noPart INT, msg CHAR(79)
LET noPart = 1000

To supply new versions of the messages, you need only provide a new source file and
compile it with the message compiler. The function calls in your application remain
the same.

C-48 Four J’s Business Development Language User Guide

Handling Code-Set Conversion

Handling Code-Set Conversion

The process of converting characters at the locale of the 4GL application to characters
at the locale of the database server (or vice versa) is called code-set conversion. If
your application needs to run on computers that encode different character sets, it
might be necessary to enable code-set conversion. This section provides some
background and details.

Code-set conversion is performed by INFORMIX-NET; no explicit code-set

conversion is done by 4GL. Figure C-3 shows the relationship between 4GL,
INFORMIX-NET, and the database.

Figure C-3
Processes and Their Locales

CLIENT_LOCALE DB_LOCALE

4GL INFORMIX-NET Database

The code sets in the CLIENT_LOCALE can differ from those in DB_LOCALE. In the
CLIENT_LOCALE, the code sets (which are specified in locales) use code points that
are pre-defined by Microsoft standards. The code sets that are used in the
DB_LOCALE tend to use characters that are based on UNIX conventions, if the appli-
cation is designed to access legacy data.

Code-set conversion is done by way of a code-set conversion file. Files for code-set
conversion between CLIENT_LOCALE and DB_LOCALE need to be present on the
client. For conversion to take place, conversion files need to be present in the
%informixdir%\gls\cv directory.

For details of converting between client and server code sets, see the sections that
follow. For more information, see the Informix Guide to GLS Functionality.

Global Language Support C-49

What Is Code-Set Conversion?

What Is Code-Set Conversion?

Different operating systems sometimes encode the same characters in different ways.
For example, the character a-circumflex is encoded:

• in Windows code page 1252 as hexadecimal 0xE2.

• in IBM CCSID 437 as hexadecimal 0x83.

If the encoding for a-circumflex on the Windows system is sent unchanged to the IBM
system, it will be printed as the Greek character gamma. This happens because, on
the IBM system, gamma is encoded as 0xE2.

This means character data strings that are passed between two computers using
different character set encodings must be converted between the two different
encodings. Otherwise, character data originating from one computer will not be
correctly displayed or processed on the other computer.

This appendix uses the term code set in the same way the Windows documentation
uses the terms character set and code page.

Converting character data from one encoding schema to another is called code-set
conversion. If a code-set conversion is required from computer A to computer B, it
is also required from computer B to computer A. You must explicitly enable code-set
conversion; no conversion is done by default. (Details on enabling code-set
conversion appear in “Enabling Code-Set Conversion for Windows” on page C-52.)

What Code-Set Conversion Is Not

Code-set conversion is not a semantic translation; that is, it does not convert words
between different languages. For example, it does not convert between English yes
and French oui. It only ensures that each character is processed and printed the same,
regardless of how the characters are encoded.

Code-set conversion does not create a character in the target code set if the character
exists only in the source code set. For example, if the character a-circumflex is being
passed to a computer whose code set does not contain an a-circumflex character, the
target computer will never be able to exactly process or print the a-circumflex
character. This situation is described in more detail in “Mismatch Processing” on
page C-51.

C-50 Four J’s Business Development Language User Guide

What Data Values Are Converted

When You Do Not Need Code-Set Conversion

You do not need code-set conversion in any of the following situations:

• The client and the server are on the same computer.

• The code set of your client and of all the databases to which you are
connecting are the same.
• The subset of characters that you will be sending between the client and the
server are encoded identically. For example, if you are sending only English
characters between a client and a server, and each English character has the
same encoding on both computers, no code-set conversion is required. In
this case, the non-English characters can have different encodings.
• The character-string data values are passed from the client to the server
for storage only and are neither processed nor printed by the server.
For example, no code-set conversion is required if a client:
•• passes character-string data to the server.
•• does not process or print the data on the server computer.
•• retrieves the same data for processing or printing on computers that use
the same code set as the client that populated the database.

Sorting data by using the ORDER BY statement or retrieving data by using a LIKE or
MATCHES clause, however, will probably produce erroneous results if the data
strings are not converted before they are stored.

What Data Values Are Converted

If you enable code-set conversion, data values are converted by INFORMIX-NET PC
from the 4GL client to the database server, and from the server to the client. The
CHAR, VARCHAR, and TEXT blob data types are converted, as are column names,
table names, database names, and SQL command text.

Mismatch Processing
If both code sets encode exactly the same characters, then mismatch handling is
unnecessary. If the source code set contains any characters that are not contained in
the target code set, however, the conversion must define how the mismatched
characters are to be mapped to the target code set.

Global Language Support C-51

Enabling Code-Set Conversion for Windows

The four ways code-set conversions handle mismatch processing are as follows:

• Round-trip conversion. This maps each mismatched character

in the source code set to a unique character in the target code set. On the
return, the original character is mapped back to itself. This guarantees that
a two-way conversion will result in no loss of information; however, data
converted in only one direction might confuse the processing or printing on
the target computer.
• Substitution conversion. This maps all mismatched characters in the
source code set to a single specific character in the target code set that serves
to highlight mismatched characters. This guarantees that a one-way
conversion will clearly show the mismatched characters; however, a two-
way conversion will result in information loss if mismatched characters are
transferred.
• Graphical replacement conversion. This maps each mismatched character
in the source code set to a character in the target code set that resembles the
source character (this includes mapping one-character ligatures to their two-
character equivalents). This might confuse printing on the target computer.
Round-trip conversions should contain as many graphical replacement
conversions as possible.
• Substitution plus graphical replacement. This maps as many mismatched
characters as possible to their graphical replacements, and maps the
remaining mismatched characters to the substitution character.

Informix-supplied code-set conversion source files have header comments that

indicate which method was used.

The following information is specific to Windows. Information for UNIX appears in

“Enabling Code-Set Conversion for UNIX” on page C-56.

Enabling Code-Set Conversion for Windows

Code-set conversion on Windows is handled by INFORMIX-NET for Windows. There
is no portable way to determine which code set an operating system is using, so you
must tell INFORMIX-NET which code set is being used by all the databases to which
your client will be connecting in a single connection.

C-52 Four J’s Business Development Language User Guide

Enabling Code-Set Conversion for Windows

For INFORMIX-NET to work correctly, all keyboard input, terminal output, and file
input and output must use the same code set on the client computer. All databases to
which your application connects during a single connection must also use the same
code set.

Follow these steps to establish code-set conversion. Each step is described in more
detail in the paragraphs that follow.

To establish code-set conversion

1. Determine the code set that is used by the client.

2. Determine the code set that is used by all the databases to which this client
will connect in a single connection.
3. Determine whether you have an Informix-defined code-set conversion that
is suitable for use between the client and database code sets.
4. Determine the Informix-defined code-set names that are used to identify the
client and server code sets.
5. Assign the Informix-defined code-set names to the CLIENT_LOCALE and
DB_LOCALE entries in the Windows 9x registry through the Setnet32
utility, or in the InetLogin structure (login.h file). Programs deployed on
Windows 3.1 can set these entries in the [Environment] section of the
informix.ini file.
6. Launch the 4GL application.

You must modify applications that write blobs to a database to set loc_loctype (in the
locator structure loc_t) to SQLBYTE or SQLTEXT. Setting this enables INFORMIX-
NET to determine if you are writing a binary blob (SQLBYTE) that should not be
converted, or a text blob (SQLTEXT) that should be converted. You do not need to set
this parameter for reading blob data.

Determining the Code Sets Used by the Client and Database

Because each operating system has its own way of declaring the code set it is using,
see your Windows system documentation or your system administrator to determine
the code set that is used by the client computer.

Your system administrator should also know which code set is being used by the
database.

Global Language Support C-53

Enabling Code-Set Conversion for Windows

Determining the Available Code-Set Conversions

All the code-set conversions available to you are located in the
%informixdir%\gls\cv directory. Where %informixdir% is the installation
directory in which INFORMIX-NET is installed.

The object file for each conversion has the suffix .cvo. The corresponding source file
for each conversion has the suffix .cv. You need two object files for each conversion,
one for the client-to-server direction and one for the server-to-client direction. The
following table lists a few examples of code-set conversion files that are currently
available.

Code Sets Conversion Files

1250 to and from 852 04E20354.cvo and 035404E2.cvo

1250 to and from ISO8859-2 04E20390.cvo and 039004E2.cvo

1251 to and from 856 04E30362.cvo and 036204E2.cvo

1251 to and from ISO8859-5 04E3E004.cvo and E00404E3.cvo

1252 to and from 437 04E401B5.cvo and 01B504E4.cvo

1252 to and from ISO8859-1 04E40333.cvo and 033304E4.cvo

1252 to and from 850 04E40352.cvo and 035204E4.cvo

Determining the Informix-Defined Name of a Code Set

Each code-set conversion source file indicates the Informix-defined names of the
code sets that it converts in its header comment. Use these names in the InetLogin
structure or (for Windows applications only) in the informix.ini file to tell
INFORMIX-NET what conversion to perform.

The names are defined in the Informix code-set name registry file. This file is named
registry and is located in the directory %informixdir%\gls\cm.

C-54 Four J’s Business Development Language User Guide

Enabling Code-Set Conversion for Windows

Specifying the Conversion Filenames Using INFORMIX-NET

To enable code-set conversion for INFORMIX-NET, assign the Informix-defined
code-set names to the CLIENT_LOCALE and DB_LOCALE entries in the InetLogin
structure (see the login.h file). For applications deployed on Windows 3.1, you can
add an entry to the informix.ini file with the format:
CLIENT_LOCALE=code-set name of client machine
DB_LOCALE=code-set name of all databases

For example:
CLIENT_LOCALE=1252
DB_LOCALE=ISO8859-1

If your application must run in more than one locale with different code sets, it is
better to set the entries programmatically in the InetLogin structure, rather than
setting the entries with the Setnet32 utility (for Windows 9x and Windows NT appli-
cations) or in the informix.ini file (for Windows 3.1 applications).

You can also set these and other database environment variables through the
Setnet32 program: start Setnet32, and click MORE to display the second page of
options.

To change to a different code-set conversion, close the connection by exiting from

the 4GL application. Then set new values for CLIENT_LOCALE and DB_LOCALE
and restart the application.

To disable code-set conversion through the InetLogin structure, set

CLIENT_LOCALE and DB_LOCALE to NULL or to the same code set. (To disable
code-set conversion on Windows applications, delete the CLIENT_LOCALE and
DB_LOCALE entries from the informix.ini file.)

To establish code-set conversion

1. Set the SQL_TRANSLATE_DLL parameter to the name of the DLL that

contains the character translation functions.
2. Set the SQL_TRANSLATE_OPTION parameter to a number that indicates
the current translation option.
Options are specific to the driver-specified translation DLL.

Global Language Support C-55

Enabling Code-Set Conversion for UNIX

Enabling Code-Set Conversion for UNIX

Code-set conversion on UNIX is handled by UNIX environment variables.

To establish code-set conversion on UNIX

1. Determine the code set used by the client.

2. Determine the code set used by all the databases to which this client will be
connecting in a single connection.
3. Specify the conversion filenames.
4. Start the application.

Determining the Code Sets Used by the Client and Database

Because each operating system has its own way of declaring the code set it is using,
consult your UNIX operating system documentation or your system administrator to
determine the code set used by the client computer.

Your system administrator should also know which code set is being used by the
database.

Specifying the Conversion Filenames

Set the DBAPICODE environment variable to specify a code set that has a mapping
file in the message directory $INFORMIXDIR/msg (or a directory pointed to by the
LANG or DBLANG value). The Informix crtcmap utility helps you to create mapping
files.

For more information, see the Informix Guide to SQL: Reference.

C-56 Four J’s Business Development Language User Guide

Symbols
.per file
editing for buttons 6-7

Numerics
4gluser.msg file C-32
4GL functions, using 6-8
7.x libraries, finding B-8

A
a-circumflex character, coding C-50
Alphanumeric characters C-25
ALS (Asian language support) C-3, C-36
Application Container, setting default size 7-8
Application Container, setting title 7-8
Applications
Windows, starting 5-22
ar42o 4-38
ar42o script 4-26
Architecture, Four J’s BDL 1-5
Arcs, drawing 7-37
Arrays
differences from 4GL 1-7
displaying a row 5-26
Asian Language Support (ALS) C-3, C-38
Asian languages C-4, C-15, C-28

B
Bidirectional text processing C-17
Big-5 code page C-21
Binary blob C-53
Bitmaps, implementing 6-11
Blobs, text C-25
Index i
Button Fields 6-15
Buttons 6-6
adding to a form 6-10
implementing hot-key 6-6
implementing menu 6-6
No Key B-14
Byte-based string operations C-29

C
C code
compiling to 4-19
example 4-19
C compiler, GNU A-8
C functions
returning key codes from 5-20
using in 4GL applications 4-9
C language A-7
Canadian French language code C-44
Castilian Spanish language code C-44
CC environment variable A-7
Channel
closing 5-11
error codes 5-11
extensions 5-6
opening a file 5-7
opening a pipe 5-8
reading data 5-9
setting default separator 5-9
writing data 5-10
CHAR data type C-16
Character filter, creating 5-21
Character set C-12, C-50
Character string printable characters C-24
Characters, special B-10

ii Four J’s Business Development Language User Guide

Check boxes, implementing 6-12
Chinese language C-4, C-15, C-21
Circles, drawing 7-36
Client locale C-22
Client/server architecture 1-5
CLIENT_LOCALE environment variable C-24, C-36, C-40, C-55
Closing a channel 5-11
Closing a window 7-12
Code page 1252 C-40
Code points C-12, C-49
Code set C-13
Code-set conversion
files C-54
handling C-49
tables C-24
Collation order C-14, C-17, C-27
COLLCHAR environment variable C-17
Colors
changing line 7-34
specifying drawing 7-33
Column name C-26
Combo Box Fields
implementing 6-16
Comments C-24
Compatibility of servers C-3
Compilation
sample program 3-4
to C code 4-19
tools for 4-26
Composite characters C-4, C-21, C-28
Configuration
Four J’s BDL 8-4
general GUI 8-17
GUI 8-21
menu style 8-20
Index iii
Constraint name C-26
crtcmap utility C-56
Currency symbols C-29
Cursor name C-26
Cyrillic alphabet C-21

D
Danish language code C-44
Data types
CHAR C-16
NCHAR C-14, C-16, C-17
NVARCHAR C-14, C-16, C-17
VARCHAR C-16
Database name C-26
Datetime 1-7
DB_LOCALE environment variable C-36, C-39, C-55
DBAPICODE environment variable C-36
DBASCIIBC environment variable C-36
DBCODESET environment variable C-36
DBCONNECT environment variable C-36
DBCSOVERRIDE environment variable C-36
DBDATE environment variable C-35, C-41
DBFORMAT environment variable C-35, C-41
DBLANG environment variable C-41
DBMONEY environment variable C-35, C-41
DBNLS environment variable C-17
DDE
using 5-11
Debugger C-23
Decimal point C-41
Deployment C-5, C-23
Diacritical marks C-13
Dialog boxes, creating 7-13
Differences from 4GL 1-7

iv Four J’s Business Development Language User Guide

DISPLAY 1-9
DISPLAY ARRAY statement
extension of 5-17
triggers for 1-13
DISPLAY environment variable 8-19
Display extensions 7-3
Display width C-29
Drawing area, selecting 7-32
Dutch language code C-44

E
East Asian languages C-28
Eight-bit clean C-12
Emulator, UNIX, starting 5-22
en_us.1252@dict C-15, C-17
en_us.1252@dict locale C-27
en_us.8859-1 C-17
envfcomp file 3-3
Environment settings C-22
Environment variables
CC A-7
CLIENT_LOCALE C-24, C-36, C-40, C-55
COLLCHAR C-17
DB_LOCALE C-39
DBAPICODE C-36
DBDATE C-29, C-35
DBFORMAT C-29, C-35, C-41
DBLANG C-41
DBMONEY C-35, C-41
DBNLS C-17
DISPLAY 8-19
FGLCC 3-3, A-4
FGLDBPATH A-2
FGLDBS 3-3

Index v
FGLDEBUGON A-7
FGLDIR 3-3, A-3
FGLGUI 1-14, 3-4, 7-5, A-2
FGLLDPATH A-4
FGLLIBSQL 3-3, A-5, B-9, B-10
FGLLIBSYS 3-4, A-6, B-10
FGLRUN A-4
FGLSERVER 8-19
FGLSHELL 3-4
FGLSQLDEBUG A-6
GCC A-8
GCC_EXEC_PREFIX A-8
GCCDIR A-8
INFORMIXDIR 3-3
INFORMIXHOST 8-13
INFORMIXPROTOCOL 8-11
INFORMIXSERVER 8-13
INFORMIXSERVICE 8-11
INFORMIXSQLHOSTS 8-13
LANG C-45
LC_COLLATE C-17, C-27
LD_LIBRARY_PATH 3-4
PATH 3-4, A-3, A-9, A-10
returning the value C-44
SERVER_LOCALE C-36
setting 3-3
setting for the compiler 4-4
setting in Windows Registry C-22
setting through Setnet32 C-44
TCL_LIBRARY A-10
TCLDIR A-9
TK_LIBRARY A-10
Windows system language variables C-43
WINSTATIONNAME 8-19
Error messages and internationalization C-35

vi Four J’s Business Development Language User Guide

Example C-code program 4-19
Example P-code program 4-7
Extended ASCII character sets C-12
Extensions to the 4GL language 6-3

F
FGL_GETENV( ) function C-44, C-45
fgl2c 4-26, 4-29, 8-17, A-3, B-14
fgl2p 4-26, 4-27, A-4
FGLCC environment variable 3-3, A-4
fglcomp 4-32
fglcomp program 4-26
FGLDBPATH environment variable A-2
FGLDBS environment variable 3-3
FGLDEBUGON environment variable A-7
FGLDIR environment variable 3-3, A-3
fglfontsel program 4-41
fglfontsel, fglfontsel.42e 4-45
fglfontsel.42e program 4-41
fglform 4-35
fglform compiler 1-14, 4-26
FGLGUI environment variable 1-14, 3-4, 7-5, A-2
fglinstall 4-47
fglinstall script 4-46
FGLLDPATH environment variable A-4
FGLLIBSQL environment variable 3-3, A-5, B-9, B-10
FGLLIBSYS environment variable 3-4, A-6, B-10
fgllink 4-33
fgllink program 4-26
fglmkmsg 4-37
fglmkmsg program 4-26
fglmkmsg utility C-4, C-7
fglmkrun script 4-13
fglmode 4-42

Index vii
fglpager 1-13, 4-47
fglpager command 1-13
fglpager script 4-46
fglprofile file
editing for buttons 6-7
FGLRUN environment variable A-4
fglschema 4-36, A-2
fglschema script 4-26
FGLSERVER environment variable 8-19
FGLSHELL environment variable 3-4
FGLSQLDEBUG environment variable A-6
fglWrt 4-48
fglWrt program 4-46
fglX11d 4-48, 8-19, A-7
fglX11d daemon 4-46
Field names, returning 5-25
Field values
returning 5-26
setting 5-26
Fields
retrieving information from 7-9
returning a value after modification 5-23
File extensions
.cv C-54
.cvo C-54
.iem C-48
.ini C-43, C-45
.msg C-32
File, opening with channels 5-7
Filename C-26
Filter, creating a custom character 5-21
findlib.sh 4-39
findlib.sh script 4-26
Finnish language code C-44
Font requirements C-13

viii Four J’s Business Development Language User Guide

Formal argument C-26
Forms, compiling 4-5
French language C-33
French language code C-44
Function name C-26
Functions, using 4GL 6-8

G
GB 2312-80 code page C-21
GCC A-8
GCC compiler, and SCO B-13
GCC environment variable A-8
GCC_EXEC_PREFIX environment variable A-8
GCCDIR environment variable A-8
German language C-33
German language code C-44
GL_DATE environment variable C-35
Glossary of localization terms, keeping C-33
GLS
servers C-3
GNU C compiler A-8
Graphical replacement conversion C-52
Greek characters C-50
Greek language C-21
GUI configuration settings 8-17

H
Help messages
compiling 4-5
translating C-28
High-order bit C-12

Index ix
I
Icelandic language code C-44
Icon modification C-28
Identifiers C-25
Index name C-26
InetLogin structure C-53, C-55
informix.ini file C-55
INFORMIXDIR environment variable 3-3
INFORMIX-ESQL/C C-13
INFORMIXHOST environment variable 8-13
INFORMIX-NET C-49, C-55
INFORMIX-NET PC C-3
INFORMIXPROTOCOL environment variable 8-11
INFORMIX-SE database server C-3
INFORMIXSERVER environment variable 8-13
INFORMIXSERVICE environment variable 8-11
INFORMIXSQLHOSTS environment variable 8-13
Installation 2-3
Internal data file corrupted error, troubleshooting B-11
International Language Supplement C-20
Internationalization
codeset conversion C-49
enabling for UNIX C-56
enabling for Windows C-52
definition C-12
fonts C-32
keyboard layouts C-32
measurement systems C-31
messages C-47
overview of methodologies C-34
paper size C-32
reports C-32
translation checklist C-33
ISO 8859 C-12

x Four J’s Business Development Language User Guide

ISO Standard A4 C-32
Italian language code C-44

J
JA 7.20 supplement C-20
Japanese language C-4, C-15, C-20, C-21, C-33

K
KEY 1-8
Key binding, removing 7-30
Key code values, returning 5-18
KEY Field attribute, setting 6-8
Kinsoku processing C-28
KO 7.20 supplement C-20
Korean language C-4, C-20, C-21
KSC 5601 code page C-21

L
LANG environment variable C-45
Language codes C-44
Language-sensitive files C-46
Language supplement C-20
Language variable C-43
Latin alphabet C-21
LC_COLLATE environment variable C-17, C-27
LD_LIBRARY_PATH environment variable 3-4
Length of identifiers C-25
Libraries, 7.x, finding B-8
Libraries, system, finding B-10
licencef4gl 4-44
licencef4gl script 4-41
License configuration 8-13
Line width, setting 7-34

Index xi
Line, drawing 7-36
Linking modules 4-8, 4-20
List boxes 6-4
Locale ID C-43
Locale variables C-45
Locales
client C-22, C-36, C-40, C-55
server C-22, C-36, C-39, C-55
Localization
defined C-12
guidelines C-33
Localized collation order C-14
Logfile names C-25, C-26
Logical characters C-13, C-29
Logical-character-based operations C-29
login.h file C-53

M
Mapping files C-56
Memory fault, troubleshooting B-15
Menus
default keys 8-30
differences from 4GL 1-8
in multibyte locales C-28
style configuration 8-20
Message box, creating 7-13
Message Compiler C-4, C-7, C-23
Microsoft Windows Programmer’s Reference C-33
Mismatch handling C-51
Modern Spanish language code C-44
Modifying fields and returning a value 5-23
Mouse management functions 7-29
Mouse usage 1-8
Multibyte locale C-29

xii Four J’s Business Development Language User Guide

N
Named values C-25
Native Language Support (NLS) C-16, C-33, C-38
NCHAR data type C-14, C-16, C-17
NLS functionality C-33
NLS servers C-16
No Key buttons B-14
Non-ASCII characters C-24
Non-composite Thai characters C-4, C-21
Non-English characters C-51
Nonprintable characters C-24
Norwegian language code C-44
NVARCHAR data type C-14, C-16, C-17

O
Opening a file with channels 5-7
Opening a pipe with channels 5-8
Ovals, drawing 7-35

P
P code
compiling to 4-7
example 4-7
returning key codes from 5-19
pager.42e 4-47
pager.42e command 1-13
pager.42e script 4-46
Paper size C-32
Partial characters C-29
Partitioned application C-22
PATH environment variable 3-4, A-3, A-9, A-10
Pathname C-26
People’s Republic of China C-20, C-21

Index xiii
Pipe
opening 5-8
writing data to 5-10
Polygons, drawing 7-38
Portuguese language code C-44
Prepared statement name C-26
Printable characters C-24
PROMPT statement
differences from 4GL 1-9

Q
Quoted string C-25

R
Radio Buttons, implementing 6-14
Reading data from opened channel 5-9
Rectangles, drawing 7-35
Registry file C-54
Registry, setting environment variables in C-22
Relational operators C-14, C-27
Remove key binding 7-30
Report name C-26
Report pager 1-13
Reports, differences from 4GL 1-8
Retrieving information from a field 7-9
Retrieving information from a window 7-10
Returning a field value 5-26
Returning field names 5-25
Returning key code values 5-18
Returning value of an environment variable C-44
Returning values after changes 5-23
Returning values after mouse click 7-29
Round-trip conversion C-52
rtsinstall 4-47

xiv Four J’s Business Development Language User Guide

rtsinstall script 4-46
Runner, building 4-12
Russian language C-33

S
Schema file, generating 4-6
SCO Open Server 5, and GCC compiler B-13
Screen array, displaying a row 5-26
Screen GUI
configuration settings 8-21
Screen record without size 1-14
Scrolling fields, implementing 6-17
Separator, setting default with channels 5-9
Server compatibility C-3
Server locale C-22
SERVER_LOCALE environment variable C-36
Setnet32 utility C-22, C-44, C-55
Setting compiler environment variables 4-4
Setting field values 5-26
Shift-JIS code page C-21
Single-byte locale C-29
Size, setting default for application container 7-8
Sorting data
in a query C-27
in a report C-27
Spanish language C-33
Special characters B-10
SQL identifiers C-25
SQL_TRANSLATE_DLL parameter C-55
SQL_TRANSLATE_OPTION parameter C-55
SQLBYTE data type C-53
sqlexit statement 1-8
SQLTEXT data type C-53
Starting a Windows program from UNIX B-16

Index xv
Statement label C-26
Statically linked runner, building 4-12
Stored procedure C-26
Streams
troubleshooting B-12
writing data to 5-10
Strings
character C-24
quoted C-25
Substitution conversion C-52
Substrings C-30
Swedish language code C-44
Synonym, SQL identifier C-26
System libraries, finding B-10

T
Table name C-26
Table-based localization C-46
Taiwanese C-20, C-21
TCL/TK interpreter A-9
Tcl/Tk interpreter A-9
TCL_LIBRARY environment variable A-10
TCLDIR environment variable A-9
TCP/IP 8-18, B-7
Text blobs C-25, C-53
Text geometry C-28
Text insertion point, specifying 7-33
Text labels C-28
Text, drawing 7-37
TH 7.20 supplement C-20
th_th.thai620 C-4, C-21
Thai language C-4, C-21, C-28
Title, setting for Application Container 7-8
TK_LIBRARY environment variable A-10

xvi Four J’s Business Development Language User Guide

Toolbars
4GL extension 1-14
Translation C-34
as part of localization C-12, C-33
checklist C-34
Turkish language C-21

U
U.K. English language code C-44
U.S. English language code C-13, C-44
Underscore ( _ ) symbol C-25
UNIX system language variables C-45
UNIX-based servers C-3, C-49
Uppercase letters C-27

V
VARCHAR data type C-16
Variable name C-26
View name C-26

W
Western European languages C-21
White-space characters C-13, C-25, C-30
Window, closing 7-12
Window, retrieving information from 7-10
Window, setting active 7-11
Windows applications, starting 5-22
Windows Front End
checking for 7-6
Windows help facility C-4, C-23, C-28
Windows program, starting from UNIX server B-16
WINSTATIONNAME environment variable 8-19
Word length C-31

Index xvii
Workarounds for common problems B-1

X
X/Open C-21
X11 8-19, 8-30, 8-31, A-7

Z
ZHCN 7.20 supplement C-20
ZHTW 7.20 supplement C-20

xviii Four J’s Business Development Language User Guide