README.TXT
ESL Production System for OS/2, VERSION 4.00              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 the ESL Production System for OS/2. 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
====================
Existing ESL 3.00 applications will have to be recompiled in order
to execute with ESL 4.00.

Performance
==========
ESL contains a number of enhancements and new features that can
contribute greatly to the usability and functionality of your
applications.  However, note that, like any other software package,
performance improvements are dependent on the nature of your
application.

ESL Physical vs. Logical DLL Names
=======================================
With version 4.00, you can simultaneously run ESL applications that have
been compiled under different versions of ESL; for example, under EASEL/32
version 3.00 and ESL version 4.00.  You may only use one version prior to
EASEL/32 3.00 concurrently with versions 3.00 or later. For example, you may
concurrently run ESL 4.00, EASEL/32 3.00 and EASEL/2 2.1 but not ESL 4.00,
EASEL/2 2.1, and EASEL/2 2.0. As part of the implementation of
this feature, we assign a suffix number to each of the system DLL filenames,
then map that name to a logical DLL name.  Make sure the LIBPATH in your
CONFIG.SYS file references the DLL directories of all versions of ESL you
are running concurrently.  If you are using ESL versions 3.0 or higher, make
sure that you reference only the latest ESLDMT.DLL in your LIBPATH.  Do this
by renaming older versions of this file to a name such as "ESLDMT.OLD." If the
latest ESLDMT.DLL is not in your LIBPATH, you may get unpredictable results,
including the following runtime warning:

        Warning: old version of ESLDMT.DLL found - resources may not be
        completely freed.

The DLL suffix number for this release is 04.  Following is a list of the
logical filenames used by ESL and the physical files to which they map:

Logical      Physical
-------      --------
DATELIB      DATELB04
ESLAPPC      EAPPC04
ESLACDI      ESLACD04
ESLC         ESLC04
ESLCICS      ESLCCS04
ESLCMSRV     ESLCOM04
ESLCOB       ESLCOB04
ESLDDE       ESLDDE04
ESLHELP      ESLHLP04
ESLLIB       ESLLIB04
ESLSTR       ESLSTR04
ESLTBL       ESLTBL04
FILEIO       FILEIO04
LOCAL        LOCAL04
MATHLIB      MATHLB04
MESSAGE      MESSGE04
SERIAL       SERIAL04
ETSCLNT      ETSCLN04
EDS          EDS04
EDB2         EDB204

In addition, the following files are installed in the ESLEWB\DLL directory for
use with ESL DB/Assist:

EDBC         EDBC04
ESLMOUSE     ESLMOU04
ESLCCP       ESLCCP04
EDBFILE      EDBFIL04

Finally, this file is installed in the ESLEWB\DLL directory for use with
ESL CommBuilder:

FILEOPEN     FILOPN04

Create a command file for each version of the compiler or runtime you wish
to execute.  Specify the full path for EPARSE.EXE and ESLRUN.EXE.  Also, be
sure to include the -f command line option to ensure that the correct version
of CONFIG.ESL is used.  The command file should dynamically set the PATH to
ensure that the correct version of ESL is executed.  The compiler command
file (named COMP40.CMD) might look like this:

      @echo off
      if exist %1.ebi del %1.ebi
      set SAVEPATH=%PATH%
      set SAVEDPATH=%DPATH%
      set PATH=e:\eslos2;%PATH%
      set DPATH=e:\eslos2;%DPATH%
      e:\eslos2\eparse -e comp40.err -f e:\eslos2\config.esl %1 %2 %3 %4 %5 %6
      set PATH=%SAVEPATH
      set DPATH=%SAVEDPATH%

The runtime command file (named EASEL40.CMD) might look like this:

      @echo off
      if exist %1.ebi del %1.ebi
      set SAVEPATH=%PATH%
      set SAVEDPATH=%DPATH%
      set PATH=e:\eslos2;%PATH%
      set DPATH=e:\eslos2;%DPATH%
      e:\eslos2\eslrun -e comp40.err -f e:\eslos2\config.esl -config %1 %2 %3 %4 %5 %6
      set PATH=%SAVEPATH
      set DPATH=%SAVEDPATH%

Note the -config command line parameter.  Use this in your runtime command
file to display in the errorlog the directories from which the DLLs are
loaded.

For more information, refer to Section 1.6 (the description of the MAPENTRY=
specification in the CONFIG.ESL file) and Section 1.8 ("Using Multiple
Versions of EASEL") in the "ESL System Support for OS/2" manual.

Using ESL DB/Assist with Multiple Versions of ESL
===============================================
If you are running different versions of ESL simultaneously and you want
to use the ESL DB/Assist tool, be sure to use the -f command line option
when starting ESL DB/Assist and provide the full pathname of the CONFIG.ESL
file that resides in the ESLOS2 directory.

==========================================================================
Third-Party Software: Versions Tested with ESL 4.00
==========================================================================
Because ESL Workbench and ESL are 32-bit enabled, we have tested
them with the 16-bit and 32-bit Application Programming Interface(s) (APIs)
of a variety of third-party software products.  Following are lists of the
tested products and the API with which we have tested them.

                          Third Party                   Third Party
Easel EXE/DLL           Product/Version                   API Type
=============           ===============                 =============

ESLCOM04.DLL            CM/2 1.01, 1.1                  (16-bit API)
                        OS/2 Extended Services 1.0      (16-bit API)

ECSFIELD.EXE            CM/2 1.01, 1.1                  (16-bit API)
                        OS/2 Extended Services 1.0      (16-bit API)

ESLCICS04.DLL           CICS OS/2 2.0 UN59267*          (16-bit API)

ESLSQLOR.EXE            Oracle 6.0.34                   (32-bit API)
ESLSQL07.EXE            Oracle 7.0.00                   (32-bit API)

ESLSQLDB.EXE            DB2/2 1.0                       (16-bit API)

ESLSQLSY.EXE            Sybase SQL Server 4.6           (32-bit API)

ESLSQLMS.EXE            Microsoft SQL Server 4.2a       (16-bit API)

16bit\ESLSQLSY.EXE      Sybase SQL Server 4.2           (16-bit API)

ESLSQLED.EXE            EDA/SQL 1.3                     (16-bit API)
EDAOS2.DLL
EDAMEM.DLL

16bit\ESLSQLOR.EXE      Oracle 6.0.34                   (16-bit API)

* Don't use CICS OS/2 2.0 UN55531 with ESL

Note that where there are both 16-bit and 32-bit versions of ESL support
for various third party software, the 16-bit versions are put into a
\16bit subdirectory of the base ESL directory.


========================================================================
Exernalizing ESL Strings
========================================================================
The following information updates material you will find in sections 5
and 6 of the new ESL Technology Family manual, ESL Internationalization.

System Requirements
===================
The program LINK386.EXE is required to externalize ESL strings.  This
program is provided as part of OS/2.  The program LINK.EXE is not needed.

Division of Text into Separate Strings
======================================
Text in static definitions of list boxes, combination boxes, dropdown list
boxes, spin buttons, and slider controls is divided into separate strings
at each "\n" ( new line) within the definition.  Text in dynamic definitions
and dynamic insert statements, however, is not divided into separate strings.

Changing Languages
==================
When EslXstrSetSecondaryDLL is called, the secondary DLL stays in effect until
the routine is called, even if EslXstrSetPrimaryDLL is called.
EslXstrSetSecondaryDLL can be called with a null string for the DLL name in
order to stop using the secondary DLL.

Use of XSREFRESH
================
When "use xsrefresh" is invoked, all menus are updated to include the new
translation of the original text, even if "change text of" has been used on
the menu.  This is unlike regions, since their text will not be refreshed if
"change text of" has been used on the region.

Strings in list boxes, combination boxes, dropdown list boxes, spin buttons,
and slider controls which were dynamically created or had text inserted
dynamically will not be updated by "use xsrefresh."

Externalized Strings and Duplicate String Literals
===================================================
There are two known cases where string literals are not externalized.

1. If a dynamically-defined table object includes "insert row values", strings
which also exist in a statically defined table, the duplicate strings will
not be exteralized. Statically-defined table object row text
should not be externalized, but dynamically defined table object row
text should be externalized. (Refer to section 5.2 of the Internalization
document for further information).

2. If a dynamically-defined slider control includes the same text strings
as defined statically for a slider control, the duplicate text in the
dynamically-defined slider will not be externalized. In this case the duplicate text
text should be externalized because dynamically defined sliders will not split
text up at the "\n" (new line).

In both these cases, the string literals should be replaced with string
constants for the externalization to be done correctly.  For example:

    ...
    horizontal slider H_SL size 100 40 at 55 10 in DR1
    range is 0 1
    insert ticks every 1 size 3
      text "ON\nOFF"
    ...
    add horizontal slider H_SL2 size 100 40 at 55 10 in DynDR2
        range is 0 1
        insert ticks every 1 size 3
        text "ON\nOFF"
    ...

would be replaced by:

    string constant SLD_Text "ON\nOFF"
    ...
    horizontal slider H_SL size 100 40 at 55 10 in DR1
    range is 0 1
    insert ticks every 1 size 3
      text SLD_Text
    ...
    add horizontal slider H_SL2 size 100 40 at 55 10 in DynDR2
        range is 0 1
        insert ticks every 1 size 3
        text SLD_Text
    ...

========================================================================
ESL Constraints
========================================================================
Spin Button Controls
====================
The ysize of a spin button is dependent on the size of the font you are using.
Therefore, specifying the ysize in the spin button definition, or dynamically
changing the size of a spin button in the Y direction will have no effect.

The "response to OBJECT" definition without the "on spin" clause will
generate a response when 1) a character is typed into the spin button, and
2) when the spin button is being scrolled. If the "on spin" clause is used,
then a response will only be taken when the spin button is being scrolled.

Slider Controls
===============
Including the "arm size" attribute for a slider also determines the breadth
(up and down direction of a horizontal slider, and left to right direction of
a vertical slider) of the slider shaft. Setting the arm HEIGHT for a
horizontal slider, and setting the arm WIDTH for a vertical slider will
determine the shaft breadth. If you wish to set the shaft breadth for a
"readonly" slider, include the "arm size" attribute in the slider definition.

It has been shown that if you dynamically change the size of a slider, the
slider may not redraw correctly. We recommend that you delete the slider and
add a new slider if dynamic changes are necessary.

Using ESL with 640x480 Resolution 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 runtime 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

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

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

Data Validation Behavior - Entry Field Masks
============================================
When you specify protected characters in a character mask, you must be
sure to include these characters in cases where you use the "change
ENTRY_FIELD text to VALUE" syntax.  For example, if you have defined a
mask for a social security number as "DDD-DD-DDDD" and you wanted to
initialize the value of that field, the VALUE might be "123-45-6789", not
just "123456789".  Bear in mind also that when you copy the "text of
ENTRY_FIELD," the value returned will also include any protected
characters.  If you evaluated this field before entering any data, it
would return the value "   -  -    ."

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 to support DCA's Communication
Workstation.

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

Touchscreen Support
===================
To use the CALDATA.DAT calibration file that is created when you run
TSCAL.CMD, you must invoke TOUCHSCR.EXE and provide the full pathname
that indicates where the CALDATA.DAT file is located.  (Remember that
TOUCHSCR.EXE cannot be running when you execute TSCAL.CMD.)  Typically,
you would include a line in your STARTUP.CMD file that provides this
full path when invoking TOUCHSCR.EXE at startup.  However, if you do not
start the touchscreen application this way, then you must type the invocation as
in the following example:

touchscr d:\eslos2\caldata.dat

Note that Easel's touchscreen support is limited to ESL objects and
does not support touching dialog control objects, menus, and
pulldowns.

COBOL Record Support
============================

The ESL Production System is delivered with a Dynamic Link Library (DLL) that
contains external conversion routines for three COBOL data types. These
conversion routines may be used within structure definitions to define fields
that will be shared with (passed to) DLLs written in the COBOL language.
(See the Programming Guide for the ESL Language for a complete description
of external conversion routines.)

Note that you must determine the size of shared fields and specify that size
in the using clause so that the field occupies the same number of bytes as the
corresponding COBOL record. Consult your COBOL documentation to determine this
number.

The COBOL data types supported, and the names of the corresponding conversion
routines are:

COBOL Type                     ESL Conversion Routine Name

PIC X(n)                       ESLCOB.COB_PICX
PIC S9(n)V(d)                  ESLCOB.COB_PICS9
COMP-5                         ESLCOB.COB_COMP5
COMP-3                         ESLCOB.COB_COMP3

ESLCOB.COB_PICS9 must always be specified with a format string
that defines the length and precision of the data.  The string
must be in the format "lenVlen".  The length specified before the
V is a positive number that indicates the number of digits in the
entire field; the length after the V indicates the number of
digits after the implied decimal place.  Note that this
convention differs sightly from typical COBOL syntax (where the
value before the V is the length of the digits before the
decimal, not of the entire field).  Do not include any embedded
spaces or other characters within the format string.

The conversion routines in ESLCOB.COB_COMP5 support external
sizes of 1, 2, and 4 bytes (where each byte is eight bits). The
declaration for each COBOL integer variable depends on the number
of digits in the PICTURE (PIC9(num)) representation.

For example, if your COBOL compiler allocates two bytes for 3-4
digits, then the field declaration for a COMP5 field containing
three digits in the LINKAGE SECTION of your COBOL source would
look like this:

01 RECORD1.
   05 FIELD1 PIC S9(3) COMP-5.

The corresponding ESL structure definition would be:

structure CobStruct is
integer CobField1 using external size 2
  "ESLCOB.COB_COMP5"
end structure

See the documentation for your COBOL compiler for specific
information about how storage space is allocated for different
numbers of digits in the picture representation.


The conversion routines in ESLCOB.COB_COMP3 support external
sizes of up to six bytes for integers and eight bytes for floats
and strings (where each byte is eight bits).  The declaration for
each COBOL integer variable depends on the number of digits in
the PICTURE (PIC9(num)) representation.  You must declare your
COMP-3 fields as SIGNED.

Note that ESL integers have a range of -2 billion to +2
billion.  This is the largest number that can be successfully
converted when using COMP-3 fields with 10 or 11 digits in the
PICTURE representation.  Values larger than that may cause
unpredictable results.  We recommend that you use floats or
strings for extremely large numbers.

When you use the format keyword to handle decimal numbers, use
the same type of format string as you would with ESLCOB.COB_PICS9

See the documentation for your COBOL compiler for specific
information about how storage space is allocated for different
numbers of digits in the picture representation.

Examples:If your COBOL compiler allocates four bytes for seven
digits (no decimal places), then the field declaration for a
COMP3 field containing seven digits in the LINKAGE SECTION of
your COBOL source would look like this:

01 RECORD1.
   05 FIELD1 PIC S9(7) COMP-3.

The corresponding ESL structure definition would be:

structure CobStruct is
integer CobField1 using external size 4
  "ESLCOB.COB_COMP3"
end structure

The following example shows use with decimal places.  The field
declarations in the LINKAGE SECTION of your COBOL source would
look like this:

01 RECORD1.
  05 FIELD2 PIC S9(5)V99 COMP-3.

The corresponding ESL structure definition would be:

structure CobStruct is
float CobField2 using external size 4
  format "7v2""ESLCOB.COB_COMP3"
end structure

The following is an example of a structure definition that uses
all four COBOL data types.

structure COMMAREA is
  string Name   using external size 100 "ESLCOB.COB_PICX"
                # COBOL PIC X(100)
  float Commission using external size 4 format "7V2"
    "ESLCOB.COB_COMP3"
                # COBOL PIC S9(5)V9(2) usage is COMP-3
  integer Type  using external size 2 "ESLCOB.COB_COMP5"
                # COBOL PIC S9(4) usage is COMP-5
  float Salary  using external size 9
                format "9V2" "ESLCOB.COB_PICS9"
                # COBOL PIC S9(7)V9(2)
end structure

The following sample program demonstrates the use of structure
support and ESL's ability to pass structure fields between
COBOL DLLs and ESL applications.

screen size 640 480

include "accel.inc"

#
# Action Bar Template Definition(s)
#

action bar PrimaryWindowABCUA is
    pulldown CobolTest text "~Program"
        separator
        choice Exit text "E~xit"
    end pulldown
end action bar

#
# Primary Window Region Definition
#
enabled visible color 26 primary textual region PrimaryWindow
    size 588 362
    at position 6 22
    color 27 foreground
    size border
    title bar "ESL Cobol Test"
    system menu
    horizontal scroll bar scroll by 6
    vertical scroll bar scroll by 16
    action bar PrimaryWindowABCUA
    minimize button
    maximize button

# The following structure was defined in the linkage section of the COBOL
# program:
#
#       01 RECORD-1.
#          05 RECORD-1-FIELD1 PIC XX.
#          05 RECORD-1-FIELD2 PIC X(25).
#          05 RECORDNUMBER1      PIC S9(4)V99.
#          05 RECORDNUMBER2      PIC S9(4)V99.
#          05 RECORDNUMBER3      PIC S9(4)V99.
#          05 RECORDNUMBER4      PIC 9(5) COMP-5.
#

# Here is declared an ESL structure that EXACTLY matches the COBOL
# structure:
#
# Note especially the following: the format PIC S9(4)V99 declared in the
# linkage section of the COBOL source is a format that requires six bytes
# total of storage: 4 to the left of the decimal, and two to the right.
# The ESL conversion routines called below reflect that TOTAL storage,
# and in the format conversion specification specify [TOTAL LENGTH]V[NUM
# DECIMALS];

structure CobolRec is
     string Initials using external size 2 "ESLCOB.COB_PICX"
     string FullName using external size 25 "ESLCOB.COB_PICX"
     float Salary using external size 6 format "6V2"
        "ESLCOB.COB_PICS9"
     float LastSalary using external size 6 format "6V2"
        "ESLCOB.COB_PICS9"
     float StockDeduction using external size 6 format "6V2"
             "ESLCOB.COB_PICS9"
     integer Age using external size 4 "ESLCOB.COB_COMP5"
end structure

# Here the structure that is declared above is referenced via an identifier
structure CobolRec Employee

# Declared here is a COBOL DLL (cobsamp.dll) that takes a structure as its
# argument.  Source for that DLL is "cobsamp.cbl"
subroutine Cobsamp (structure CobolRec: I) library "cobsamp"

# Subroutine Definition(s)
#
response to start

   # First, copy values to structure fields using ESL
   copy "DC" to Employee.Initials
   copy "Dale Cooper" to Employee.FullName
   copy 0 to Employee.Salary
   copy -99 to Employee.LastSalary
   copy 66.22 to Employee.StockDeduction
   copy 33 to Employee.Age

   add to PrimaryWindow
      insert "Initially, ESL stores these values as:\n"
      insert Employee.Initials "\n"
      insert Employee.FullName "\n"
      insert Employee.Salary "\n"
      insert Employee.LastSalary "\n"
      insert Employee.StockDeduction "\n"
      insert Employee.Age "\n"

   # In the COBOL DLL, we can see these values have been accepted
   # because they are written to "outfile", then the DLL changes the values
   # and those changes are written to "outfile" as well.
   call Cobsamp (Employee)

   add to PrimaryWindow
      insert "\nThe COBOL DLL has changed the values to:\n"
   read file "outfile" into PrimaryWindow


   # Upon return from the DLL, we can test the values of the structure
   # fields and see that the values that were changed in COBO are
   # reflected here
   add to PrimaryWindow
      insert "\nand ESL sees these changed values as:\n"
      insert Employee.Initials "\n"
      insert Employee.FullName "\n"
      insert Employee.Salary "\n"
      insert Employee.LastSalary "\n"
      insert Employee.StockDeduction "\n"
      insert Employee.Age "\n"
      insert "\nThis window will be written to a file called
        \"outfile.esl\""
   write destructive PrimaryWindow to file "outfile.esl"

response to item Exit from PrimaryWindowABCUA
   exit


COBOL COMP-3 Conversion
=======================
MicroFocus(R) COBOL allocates storage space for COMP-3 fields as follows:

      Digits in picture       Storage allocated
      representation:         in 8-bit bytes:

             1                       1
            2-3                      2
            4-5                      3
            6-7                      4
            8-9                      5
           10-11                     6
           12-13                     7
           14-15                     8


COBOL COMP-5 Conversion
=======================
MicroFocus(R) COBOL allocates storage space for COMP-5 fields as follows:

      Digits in picture       Storage allocated
      representation:         in 8-bit bytes:

            1-2                     1
            3-4                     2
            5-6                     3
            7-9                     4

Issues to note:

1) This is the default allocation scheme for SIGNED fields, since the
   ESL conversion routines treat COMP-5 fields as signed.

2) MicroFocus COBOL will allocate storage differently if you specify the
   'IBMCOMP' system directive, or if you have the 'SYNCHRONIZED' clause
   in the data-item description.

3) Since ESL conversion routines work with allocation units of 1, 2,
   and 4 bytes, you would need to 'promote' COMP-5 fields that specify 5
   or 6 digits in the picture representation to specify 7 digits in the
   picture representation.  For example:

      01 RECORD1.
         05 FIELD1 PIC S9(5) COMP-5.

   This should be modified to:

      01 RECORD1.
         05 FIELD1 PIC S9(7) COMP-5.

   The corresponding ESL structure would be:

      structure CobStruct is
         integer CobField1 using external size 4 "ESLCOB.COB_COMP5"
      end structure

================================================================
DATABASE SUPPORT
================================================================

ESL Database Services
============================================================================
ESL Database Services (EDS) is based on the SQL Access Group's Open
Database Connectivity (ODBC) application programming interface. To make
use of this, you must have installed an ODBC driver manager and a
database driver for your database management system (DBMS). ESL
4.00 works successfully with any database driver meeting
the ODBC Version 1 specification.

The Q+E ODBC Driver Pack for OS/2 has been validated with the ESL
4.00 EDS ODBC support.

NOTE
====
EDSExtendedFetch (a Level 2 function) is not available for this release.
This also applies to the following other EDS calls that work in conjunction
with EDSExtendedFetch: EDSDescribeParam, EDSSetPos, and EDSSetScrollOptions.


ORACLE
======
To use Easel's SQL executable support for Oracle under OS/2 2.x, you
must include the following line in the CONFIG.ORA file:

ORACLE_OPENFILE=255

Oracle Version 6 vs. Oracle Version 7
=====================================
ESL version 4.00 supports Oracle versions 6 and 7 running on both
client and server machines.

Sending Quoted Strings with Oracle 7.0
======================================
Due to a limitation in Oracle version 7.0, an application cannot send a quoted
string greater than 2,000 characters to an Oracle database. If this is
attempted, an Oracle error 1704 (string literal too long) will be received
from the local. A workaround to this problem is to create a SQL statement
using the Oracle PL/SQL language. The following is an example where the
variable String_SV contains a quoted string with greater than 2,000
characters:

  application SQL

    .....
  response to ....
    send "declare verylong long:='" String "';" to SQL
    send "begin insert into company1(long1) values (verylong); end;\n" to SQL

Note: The entire PL/SQL executable block must be sent on one line, or the
the entire executable block must be followed by a single "\n" as shown above.

Sybase 32-Bit -- Required Files
========================
To use Easel's SQL executable support for Sybase under OS/2 2.x,
the following Sybase DLL files must be present:

LIBNET.DLL
SQLINTL.DLL
SYBCOM.DLL
SYBCSEM.DLL
SYBDB.DLL

These files are part of the Sybase Developer's Kit; they are not
contained on the Sybase client services diskettes.  Contact your Sybase
representative if you do not have these files.

Sybase -- 16-Bit vs. 32-Bit
===========================
The 16-bit version of ESL Sybase support will only work with the 16-bit
transport layer, and the 32-bit version of ESL Sybase support will only
work with the 32-bit transport layer.  These are not interchangeable and
will produce a "Process Open Failed" message in the incorrect environment.

EDB2 Support for DB2/2 and Extended Services Database Manager
=============================================================

ESL 4.00 supports both the DB2/2 32-bit and the Extended
Services 1.x Database Manager databases.  Installed from your diskettes as the
default are EDB204.DLL, EDB2.BND and EDBC04.DLL which support the DB2/2
32-bit API.  These specific files are built with the new DB2/2 32 bit
libraries and will not work with the older 16-bit API of Extended Services
Database Manager.

If you have not upgraded to DB2/2 and are running Database Manager,
you need to perform the following steps to ensure that the Extended Services
Database Manager ESL client has the appropriate DLLs in the path.

1. Copy EDB204.DLL, EDBC04.DLL and EDB2.BND from your ESL Production
   System for OS/2 base directory, 16-bit subdirectory (ESLOS2\16BIT by
   default) to the DLL subdirectory of your ESL Production System base
   directory (ESLOS2\DLL by default). This action will replace the DLLs and
   BND files which support the DB2/2 32-bit API only.

2. Bind the EDB2.BND file to your Extended Services Database Manager
   database.


========================================================================
EDA/SQL Support
========================================================================
General Information
===================
Easel's EDA/SQL Support 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 Application.

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 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
======================================
The EDA/SQL Support for ESL is distributed with the
following Information Builders developed EDA API/SQL DLLs:

        OS/2: EDAMEM.DLL and EDAOS2.DLL

Easel's EDA/SQL 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 ESL-supplied versions are first in the
libpath when running ESL EDA/SQL applications or 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
OS/2 version 2.1. 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 2.0 can be run in OS/2 2.1 to create and modify
icons.

Use of Color 26 (Default Background Color)
==========================================
Due to an OS/2 2.1 anomaly, ESL color 26 (the default background
color) does not work for combination boxes, dropdown lists,
dropdown combination boxes, and multiple line entry fields.

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 of 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
========================================================================
FONTS.INC
=========
If you choose to include FONTS.INC in your ESL application, you must
change FONTCNT=20 to FONTCNT=40 in the CONFIG.ESL file in your ESLOS2
directory.

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 and 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. The ESL Production
System 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 the 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
=======================
The 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).

========================================================================
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 a "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.

