ESL Workbench version 4.00 README.TXT File
June 27, 1994

This file contains additional important information not covered in the
standard documentation, as well as other information you need to know
before using ESL Workbench.  Each individual client/server option
diskette also includes a README file. We recommend that you print all
README files and, after reading them, store them with your documentation.
Please refer to this information before calling Easel's Customer Support
Hotline. If this information is not clear, or you have a question that
is not covered, we encourage you to call the Customer Support Hotline
at (617) 221-2400, from 9 AM to 8 PM Monday through Thursday
and between 9 AM and 5:30 PM on Fridays, Eastern Time. If you have
access to a modem, you may also contact us via Easel Exchange, our CompuServe
electronic bulletin board system. Customers outside the United States and
Canada should call the technical support organization of the local
Easel Corporation affiliate.

===========================================================================
IMPORTANT INFORMATION
===========================================================================
Upward Compatibility
====================
For most applications you can upgrade to the 4.0 release of ESL
Workbench by importing your production EAL file, recompiling within
ESL Workbench, and saving the new project.

For projects that use ESL Workbench specific routines such as code
generation for dialog controls, a special conversion routine is needed
to convert your existing project. If you wish to have this conversion
routine sent to you, please call the Customer Support Hotline or the
technical support organization of the local Easel Corporation affiliate
as described above.

Insufficient SWAP Space Symptoms
================================
ESL Workbench requires adequate swap space to function properly. The
minimum suggested disk space for swapping is 20 megabytes.
The actual amount of swap space used will vary according to the amount
of RAM available and additional applications running on the PC.

When running ESL Workbench, if you notice symptoms such as unexpected
memory shortage messages, or the inability to open additional editors
and debug windows, please check the available swap space on your PC. To do
this accurately, task out to an OS/2 window and check the available space
on the swap drive when ESL Workbench is running. If you have less than
1 megabyte of free space on the drive, delete some files from your swap
drive and test to see whether this resolves your problem in ESL Workbench.

Note that OS/2 2.0 without the Service Pack will not decrease the size of
the swapper.dat file while the system is running. You must reboot your
machine to reclaim the disk space.

Starting ESL Workbench
========================
We strongly suggest that you start ESL Workbench from an icon on your
desktop. ESL Workbench may not behave well during a desktop shutdown if
started from the command prompt.

===========================================================================
ESL Workbench Anomalies
===========================================================================
The following is a list of known anomalies in ESL Workbench behavior.
We are currently studying these situations and, if appropriate, will be
taking corrective actions in future revisions of the product.

Debugging Drag and Drop
=======================
You can set breakpoints on the "on drag", "on drop", and "on draghelp"
responses, and on any action statement within these responses.  ESL
Workbench will allow you to also set a breakpoint on the "on dragover"
response and any action statement within an "on dragover" response, but
the Workbench debugger will ignore the breakpoint.

It is not possible to bring up the Debugger Window or any other window
during a drag operation.

For best performance when debugging drag and drop operations, we recommend
that you turn the "terp" trace off during the drag operation.  This can be
done by setting the "terp" switch in the Trace Window to "off".  If the
Trace Window is not visible, then there will be no performance issue.


Visual Editor Issues
====================
* When you cut and paste dialog objects with which actions are
associated, only the objects themselves are cut.  The pasted objects will
not include previous Generate Code selections, and their controls will not
include previous variables. In addition, the default attributes are retained.
For this reason, if code generation is turned on, recompiling a dialog
object after it has been cut and pasted back into the Layout Editor will
result in the deletion of any actions that were formerly associated with
the object.

* When a polygon, shape, or boundary is resized to be very small, and
then resized to be larger again, the drawing might become corrupted
because ESL stores coordinates in integers and precision is lost.

* If you change the parent of a radio button in the Layout Editor, group
variables are lost.

* When you paste objects in the Layout Editor, if you press the Escape
key when prompted for a unique object name, you will paste objects with
duplicate names.  This will cause errors when you update and compile.

Text in Multiple-Line Entry Fields
==================================
Even if you have selected the Word Wrap option for a multiple-line entry
field, the text is not adjusted when you resize the entry field in the
Layout Editor.  The text will be readjusted when you update and compile
the entry field.

Group Boxes
===========
In the Layout Editor, if you create a group box and then create a larger
group box that completely surrounds the first one, you will not be able
to select the inner group box until you update and compile.

Attribute Editor Issues
=======================
* In order to properly distinguish escape sequences, Attribute Editor
entry fields now consistently require that a double backslash "\\" be
used to denote a single backslash (\). For example, entering a drive and
directory location for an image region file association would require a
double backslash for each subdirectory notation.

* In the Attribute Editor, you cannot change the Colored attribute of a
textual region that has text.

* If errors are generated during a compile, then the Errors List window
will appear behind the Attribute Editor window. To see the Errors List
window, move or close the other two windows.

* For entry field validation in the Attribute Editor, if you want to type
in a year that is before 1000, you must enter the leading zeroes.  For
example, if you want to enter the year 2, you must type 0002.

Text Editor Issues
==================
Using the replace function to change multiple string instances in
combination with the verify option can sometimes yield unpredictable
results. To confirm that all strings have been replaced correctly in
the source we suggest doing a straight find after this type of
replace operation.

Miscellaneous Issues
====================
* Modules are locked in the Main view.  You can delete them through the
Project Views Manager.

* When an ESL application is in an intensive for loop, while loop, or
very large action statement, mouse and keyboard messages might be lost.
This is necessary to allow Workbench and ESL to interact.  For example,
if the ESL application is in an infinite loop, Workbench needs to be
able to get the control so that you can abort the ESL application.

* The array examiner will not work on arrays that contain more than 2075
elements.

* ESL Workbench cannot save a project to a disk drive that contains
more than four gigabytes of free space.  (The error message, however,
indicates that there is not enough space.)

Using ESL Workbench with XGA/VGA Hardware
===========================================
If you are using display hardware that provides 640x480 resolution,
but is not true VGA (for example, plasma displays on IBM P75's
configured for XGA but running without an XGA monitor), then you
should use the -novidmod command line option to avoid hardware conflicts.

When you do so, however, the following ESL color palette
functions for fullscreen applications will not work:

EslSetEgaColor
EslSetVgaColor
EslQueryEgaColor
EslQueryVgaColor

Usig these functions with the -novidmod option will result in an
errorlevel of -1, and the Query functions will return values of 0.

=====================================================================
ESL Constraints
=====================================================================
Squeeze Memory in Subroutines
=============================
Squeeze memory should not be called from within a subroutine or indirectly
from within an action routine called from a subroutine.  Whenever squeeze
memory is used ESL checks to see if a subroutine is active.  If there is an
active subroutine, ESL will send a message to the errorlog saying:

        ignoring squeeze memory: squeeze memory is not supported while
        a subroutine is active

If the squeeze memory fails because of an active subroutine, ESL will
check the low memory threshold each time a block is entered or after the
completion of the execution of an outermost response.

Squeeze memory is done implicitly with the "save program as"
statement.  We therefore, do not recommend using "save program as" within
a subroutine or from within an action routine called from a subroutine.

Table Object Row and Column Selection
=====================================
When a table object has no editable columns, the cursor is drawn around a row
if row selection is enabled, or around a column if column selection is enabled.

The "multiple row selection" attribute allows you to select one or more rows.
If the table has no editable columns, then when clicking the mouse in a
cell or pressing the space key, the row is selected.  If the table does have
editable columns, rows are selected by clicking on the row heading or by
pressing the key combination Shift-Space bar.

The "multiple column selection" attribute allows you to select one or more
columns. If the table has no editable columns, then when clicking the mouse
in a cell or pressing the space key, the column is selected. If the table does
have editable columns, columns are selected by clicking on the column heading or
pressing the key combination Shift-Space bar.

Removing Table Object Rows in a Loop
====================================
You may wish to delete all selected rows in a Table Object using a "for each
selected row" loop.  We recommend the following code for this purpose:

      response to ...
              for each selected row Row_IV in Table_TBL loop
                        remove row Row_IV from Table_TBL
                        copy (Row_IV - 1) to Row_IV
              end loop


Audio Support
=============
Easel is no longer distributing ESL support for the IBM Audio Capture and
Playback Adapter/A.

DCA's Communication Workstation
================================
Easel is no longer distributing ESL support for 3270, ESL Communication Server,
APPC, or the fields local application for DCA's Communication
Workstation.

Office Vision
=============
Easel is no longer distributing ESL support for IBM's Office Vision.

=====================================================================
Operating System Issues
=====================================================================
You must convert customized Windows fonts and DOS fonts to OS/2 fonts
before you can use them in Workbench.

===========================================================================
ESL Production System versus ESL Workbench Compiler Issues
===========================================================================
ESL Workbench more strictly flags source coding errors at compile
time than ESL. Because of the nature of the
Incremental Compiler, ESL Workbench is able to more readily identify
code duplications:

Menu Choice Qualification
=========================
Workbench requires the qualification of menu items used in more than
one menu bar. The ESL production compilers will not generate a compile error
for the example below. ESL Workbench will import and compile this
code correctly only the first time. Subsequent changes to the primary
region or its response will generate a Workbench compile error.

        action bar Primary_AB is
           pulldown Test_PD text "Test"
                 choice Choice1 text "Choice1"
           end pulldown
        end action bar

        response to item Choice1
           send "Taking response to choice1" to errorlog

        action bar Secondary is
           pulldown Test text "Test"
              choice Choice1 text "Choice1"
           end pulldown
        end action bar

Names of Regions Must be Unique
===============================
Workbench requires that region names be unique; a name used to identify
a region cannot be reused as a local variable name. The ESL compilers
will not generate a compile error for the example below. ESL Workbench
will import and compile this code correctly only the first time. Subsequent
changes to the subroutine below will generate an ESL Workbench compile error.

        subroutine EcsReadFieldRowCol( integer:Row,
                                       integer:Col,
                                       string:Data ) is
            integer FieldNo
            call EcsGetFieldNumber(Row, Col, FieldNo)
            call EcsReadField(FieldNo, Data)

        primary region Data size 300 300 at 0 0
===========================================================================
ESL DB/Assist
===========================================================================
When you add a computed column to a SELECT statement, ESL DB/Assist does not
automatically generate a GROUP BY clause.  When you validate this statement,
a SQL error message numbered SQL0122N may appear, indicating that you must
add a GROUP BY clause to the statement.  To do so, type the appropriate
GROUP BY clause in the SQL Editor window.

Building SELECT Statements in ESL DB/Assist
=======================================
We recommend that you not use character strings as labels for the result
set when building SELECT statements in DB/Assist.

ESL DB/Assist and DB2/MVS
==========================
ESL DB/Assist does not support DB2/MVS.  We suggest that a copy of the database
be developed to run on the server instead.

ESL DB/Assist in a Multi-developer Environment
==============================================
The DB/Assist tool was written in such a way that it will automatically
qualify each SQL statement with the USERID of the person who is
currently logged into Database Manager. This prevents
building SQL statements against tables created by a userid other
than the person currently logged onto Database Manager. If you have
multiple developers, it is suggested that you create a
prototype of the development database with a common userid that will be
used by the entire development team.

Note: During the database application development process, we
recommend the use of a prototype of the production database. One way to
create the prototype could be with the use of a REXX command file.
Another way to create the prototype would be with the shareware utility
named SPUFI/2. This utility can be downloaded from the DB2/2 library in
the IBM DB2/2 Family Compuserve forum.

Connecting to non-DB2/2 SAA Databases
=====================================

When connecting to SAA databases, which reside on a server other than a
DB2/2, DB/Assist will generate an error message.  This error is a
result of differences between the system tables in DB2/2 and other SAA
databases.  System tables store schema information about the
database you are working with, which is necessary when
running the DB/Assist tool. DB/Assist accesses this information by
making SQL calls into DB2/2 system tables exclusively. Therefore if you
try running against a non-DB2/2 database, DB/Assist will have
difficulties. To work around this problem we suggest creating a
prototype of the development database on DB2/2.  Access this database
during the development process. When development is complete the .BND
file that is generated during the DB/Assist compile must be bound
against the non-DB2/2 production database to run the application.

===========================================================================
EDA/SQL Support
===========================================================================

EDA/SQL General Information
===========================
The EDA/SQL Support for ESL Workbench requires the presence of EDA/Link
from Information Builders, Inc. on the PC and EDA/SQL Server on a host
computer.

EDA/Link Software is provided by IBI on a single installation diskette
that includes versions for DOS and OS/2. Installation is as documented
in the manual, "EDA/Link for DOS and OS/2 Installation and Operations".
You should ensure that your EDA/Link connection is up and running
before beginning testing of the ESL EDA/SQL Support.


Starting EDA/Link
=================
The chapter "Invoking an EDA/Link Session" in the manual "EDA/Link for DOS
and OS/2 Installation and Operations" details the steps for
invoking an EDA/Link session from your PC. In all cases, ensure
that the EDA/SQL Server is up and running before starting your
ESL application. In LU2 and asynchronous environments, at some point
before starting your ESL application, you must connect to the host
and login to the EDA/SQL Server. An "EDA>" prompt on the host command
line is presented when the server session has been started.

OS/2 Connection Considerations
==============================
For OS/2, verify that the server is up and running; starting your ESL
application in ESL Workbench will automatically invoke EDA/Link.

Testing Your EDA/Link Connection
================================
To simplify establishing an ESL EDA/SQL connection, confirm
your PC EDA/Link communications prior to testing with your ESL
application.

In addition to any test applications that your organization may have in place,
Information Builders, Inc. provides a test application for EDA/Link for
OS/2 called RDAPP.EXE. This test application is distributed
with the EDA API/SQL product. If you cannot locate this software
within your organization, you can request it from the Information Builder's
EDA/SQL hotline.

IBI Software Distributed with ESL Workbench
=============================================
The EDA/SQL Support for ESL Workbench is distributed with the
following Information Builders developed EDA API/SQL DLLs:

        OS/2: EDAMEM.DLL and EDAOS2.DLL

The EDA/SQL ESL Workbench Support requires the specific versions of
the DLLs that you have received be loaded at application execution time.
If you are running other software packages that include their own versions
of the above DLLs, ensure that the Easel-supplied versions are first in the
libpath when running ESL EDA/SQL applications in ESL Workbench.

EDA/Link V1.2
=============
In OS/2, multiple EDA/Link sessions can be established with
an EDA/SQL server simultaneously, allowing multiple versions
of ESLSQLED.EXE to be started from an ESL application.

EDA/LINK V2.0 will provide for multiple EDA/Link sessions to
multiple EDA/SQL servers for both OS/2 and Windows.

========================================================================
Operating System Issues -- OS/2 Version 2.1 only
========================================================================
Performance Degradation When Creating Dialog Controls
=====================================================
Easel has discovered a degradation in performance between OS/2 2.0 and
OS/2 2.1 with regard to the creation of dialog controls. This timing
issue is more noticible on non-IBM PCs.

IBM has opened APAR PZ10505 with a severity level of 1 (their highest
priority) to respond to this problem.  There is no correction yet.

Ending an ESL Application from the Task List
============================================
Ending an ESL application from the task list will not generate a "response
to Region_Name on close."  This is due to the way OS/2 handles messaging
for regions.

Colors of Disabled Dialog Controls
==================================
You cannot set the colors of disabled dialog controls due to the nature of
OS/2 version 2.1.

Modification of Text in a Disabled Entry Field
==============================================
Due to the nature of OS/2 version 2.1, text can be modified in a disabled
entry field if the focus is left on the entry field when it is disabled.

INS and DEL Keyboard Responses
===============================
OS/2 2.1 allows the generation of responses to the INS and DEL keys from the
numeric keyboard even though the Num Lock key is on.

Combination Boxes Containing Text in a Small Font
=================================================
Combination boxes containing text drawn in a small size font will not be
redrawn correctly.  This is due to OS/2 2.1 behavior.

Version 2.1 Icon Editor
=======================
ESL is currently incompatable with icons created with the Icon Editor
in version 2.1 of OS/2. This is due to a change in IBM's implementation of
the Icon Editor and the bitmap file format (version 1.2) it produces.
The Icon Editor from OS/2 version 2.0 can be run in OS/2 2.1 to create and
modify icons.

Clipping of Text in Dialog Controls When Upgrading to OS/2 2.1
==============================================================
OS/2 2.1 uses a system proportional font that is designed to meet the
International Standards Organization (ISO) 9241 standard and the
German DIN 66234 standard on suitable hardware.

ISO compliant fonts cause some text strings to be clipped.  If you do
not want to use ISO compliant fonts, modify the OS2.INI file to
install fonts that are not ISO compliant.  Font changes made in the
OS2.INI file are global across all applications.  If you have REXX
installed, you can type the following information into a CMD file and
use it to change the font.

           /* */
           call RxFuncAdd "SysIni", "RexxUtil", "SysIni"
           AppName = "PM_SystemFonts"
           KeyName = "DefaultFont"
           FontName = "10.System Proportional Non-ISO"
           call SysIni "USER", AppName, KeyName, FontName||"0"x
           exit

After the file has been run, shutdown and restart the system.

========================================================================
Operating System Issues -- OS/2 Version 2.x (versions 2.0 and 2.1)
========================================================================
Help Panels not Found
=====================
With certain IPF panels specified, calls to HelpDisplayHelpPanel()
or selecting F1 result in the return of an error message box instead of
the desired help panel with the OS/2 service pack installed. Call IBM
for the fix for this error; the APAR is PJ06890.

Setting Printer/Plotter Driver Properties in OS/2
=================================================
Under OS/2 2.x, there are two different ways to select printing
characteristics, such as portrait or landscape mode.  The first method
is designed to make a permanent change to the printer configuration.
The second method is used only to affect changes to the current print
job.  This can be confusing, since the dialog boxes are identical and
there is no indication as to whether you are making a permanent or job
change.

To make a permanent change to the printer driver settings:

1. Select open->settings from the printer icon.
2. From the notebook control select the "Printer Driver" tab.
3. Double click on the icon for the default printer driver.
   This will display a dialog box called "Printer Properties".
4. Select the "Device Defaults" button in this dialog box.
   This will display another dialog box containing a set of radio
   buttons that will allow you to select the printing mode.

To change settings only for the current printing job:

1. Select open->settings from the printer icon.
2. From the notebook control select the "Printer Driver" tab.
3. Select the "Job Properties" pushbutton underneath the printer icons.
   This will display the exact same dialog box that you would see in
   step 4 above.

OS/2 Default Minimize Window Behavior
=====================================
There has been some confusion about Easel's implementation of minimize
window behavior. The default OS/2 minimize window behavior is to
minimize to viewer.  This can be affected by the desktop folder
settings, but it is controlled from within the Settings folder. Similar
to other OS/2 applications, ESL uses these system settings when an
ESL window is minimized via either the pulldown minimize option or as
a result of a make <Object> minimize action statement.

Therefore, if you want your application to minimize to the desktop, you
must modify the OS/2 installation defaults from within the Settings
folder as follows:

1. Select the OS/2 System icon.
2. Select the System Setup icon.
3. Select the System icon.
4. Select the "window" notebook tab.
5. Select the "Minimize button" radio button in the "Button appearance
   for windows" section.
6. Select the "Minimize to window to desktop" radio button in the
   "Minimize button behavior" section.

========================================================================
Font Considerations
========================================================================
Referencing ESL Fonts in Dialog Control Definitions
=====================================================
By default, dialog controls can be defined with any image and outline
fonts that have been installed to PM and that have an associated ESL
font definition. ESL fonts found in ESLFONTS.FON can also be used in
dialog control definitions if they are are installed to the system then
redefined in your ESL application. Follow this procedure to install
ESLFONTS.FON to OS/2:

1. Open the OS/2 System folder.
2. Open the System Setup folder.
3. Open the Font Palette utility.
4. Click on the Edit font... pushbutton.
5. Click on the Add... pushbutton in the Edit Font dialog box.
6. Enter the full path for the ESL dll subdirectory
   (for example: c:\eslos2\dll) and click on the Add... pushbutton.
7. ESLFONTS.FON should appear in the Font files list in the
   Add New Font dialog box. Select the file.

  The installation should be complete.

PM Fonts - OS/2 2.x vs. OS/2 1.3
================================
OS/2 2.x is distributed with fewer installed image fonts (as opposed to
vector/scalable/outline fonts) than OS/2 1.3. This will affect existing
ESL programs that reference PM fonts that are no longer present under
OS/2 2.x. If an OS/2 PM font is not found to match the definition of a
font used in a program object, ESL will substitute the following:

  Text Regions:   Always substitute "medium" font
  Other Objects:  Search system for a matching vector/scalable/outline
                  font

To let you know that this substitution has occurred, ESL Workbench will
generate a warning during the incremental compile. ESL will
generate a runtime warning to the errorlog. If you would like to avoid
warning messages for the substitution of outline or vector-based fonts,
add the keyword "outline" to the specific font definition.

Text regions are most affected by the decreased number of installed
fonts, as they require fixed cell sized fonts that are not scalable.
The following fixed cell image fonts are available to the ESL
programmer from OS/2 2.x:

    System Monospaced fixed        (9 x 20)  image 10 point
    System Monospaced fixed        (8 x 16)  image 10 point
    System Monospaced fixed        (8 x 12)  image 10 point
    System Monospaced fixed        (8 x 8)   image 8 point
    Courier           fixed        (8 x 13)  image 8 point
    Courier           fixed        (9 x 16)  image 10 point
    Courier           fixed        (12 x 20) image 12 point

Note that the list above and the list below of available proportional
image fonts include fewer point sizes than previously existed in
OS/2 1.3.

    Helv       proportional (5 x 13)  image 8 point
    Helv       proportional (6 x 16)  image 10 point
    Helv       proportional (7 x 20)  image 12 point
    Helv       proportional (8 x 24)  image 14 point
    Helv       proportional (11 x 29) image 18 point
    Helv       proportional (14 x 37) image 24 point
    Tms Rmn    proportional (4 x 13)  image 8 point
    Tms Rmn    proportional (5 x 16)  image 10 point
    Tms Rmn    proportional (6 x 19)  image 12 point
    Tms Rmn    proportional (7 x 21)  image 14 point
    Tms Rmn    proportional (10 x 27) image 18 point
    Tms Rmn    proportional (13 x 35) image 24 point

========================================================================
OS/2 Version 2.0 GA Only
========================================================================
Colored Dialog Controls
=======================
OS/2 2.0 GA version will not allow the background color to be changed
for radio buttons, check boxes and combo boxes (including dropdown list
boxes and simple dropdowns). Service Pack 6055 allows setting the
background color for all controls except combo boxes and list boxes.
You can compile ESL applications with a background color specified
for these controls; however, some of the controls may not display with
the specified color(s).

Menu Choice Mnemonics
=====================
Properly specified menu choice mnemonics occasionally do not show up
within ESL Workbench. They are properly compiled for the object and
ESL Workbench will keep track of the mnemonic. This problem is due
to Program Manager and is resolved with service pack 6055.

Editing Menu Choices
====================
When editing a menu choice in the Menu Editor in the GA version of OS/2 2.0,
the associated pulldown disappears while the Attribute Editor is visible.
You must reselect the pulldown to view your changes. This is fixed in
service pack 6055.

========================================================================
OS/2 2.0 Service Pack 6055
========================================================================
IBM has issued a number of service packs for OS/2 2.0.
Service packs may be installed on top of OS/2 2.0 GA software.
Easel Corporation has performed extensive testing with service pack 6055
and has discovered changes that may adversely affect ESL programs.
In addition to reports of random Trap D's by some customers, we have
identified the following:

New System Font
===============
Although the default system font changed in service pack 6055, dialog
unit calculation did not change accordingly. Since the service pack
system font is wider than the original system font, you may notice that
your dialog object text will appear to be clipped.
If you must run existing ESL applications on a machine that has the
service pack installed, we suggest using the -u runtime option to scale
objects defined in dialog units to accomodate the new text size.

Required Installation of ESL Fonts
====================================
In order for ESL fonts to behave as expected with the service pack
and to use them in your dialog control definitions, you must install
ESLFONTS.FON as described in the "Referencing ESL Fonts in Dialog
Control Definitions" section of this README. If the ESL fonts are not
installed to an OS/2 2.0 system with the service pack, ESL font
specifications in object references are unpredictably set back to
medium.  There are two identified instances when the font gets reset to
medium:  when you return to an ESL application with change to program
statement, and in text drawing statements. In both of these cases the
specified ESL font will be displayed correctly in OS/2 2.0 GA without
having to install ESLFONTS.FON.

IBM suggests that you use the system-provided Selective Install Facility
to install new fonts (or any object) prior to installing the service
pack. They also suggest that if you use the Selective Install on a
machine with the service pack, that you reinstall the service pack.

