
   Virtual Pascal for OS/2 v1.99.A1
   VCL-compatibility using Open32
   (C) 1997 fPrint (UK) Ltd


The background of this version of VP/2
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  We at fPrint (UK) Ltd have enhanced our Pascal compiler for OS/2 to
  include most of the language features found in Borland Delphi v2, and
  made changes to the Visual Component Library source code to allow
  programs written using Delphi under Windows to be recompiled as
  native 32-bit OS/2 applications.

  For doing this, we have relied on IBM's Open32/Dapie/DAX library,
  which emulates a subset of the Win32 API and - according to IBM -
  allows developers to quickly port their Windows applications to OS/2.
  However, the Open32 library as it currently stands (Warp 3 w/FP28) is
  unstable, limited in functionality, and very slow.  Timing tests
  suggest that applications using Open32 are about 5-15 times slower
  than their native Windows counterparts.

  For this reason, fPrint has suspended further development of the
  Delphi compatible version of Virtual Pascal for OS/2, and instead
  release this archive as a downloadable upgrade to all existing users
  of VP/2. If you can find a use for it, fine!  The updated compiler,
  linker and RTL allows you to recompile your Delphi programs to OS/2,
  where they will run as native applications.  Or walk, rather.


Installation
~~~~~~~~~~~~
  To install this version of VP/2, you need to have the CD-ROMs with
  VP/2 and Borland Delphi (Either 2.00 or 2.01) available.

  Create a new directory, and unzip the files in this archive in that
  directory.  Do not use your existing VP directory for this purpose as
  files will be overwritten.  The two versions of VP (v1.10 and
  v1.99.A1) can coexist on one computer.

  Run the supplied REXX script, Install.cmd.  This script will ask you
  to insert the VP/2 CD-ROM in the drive and indicate the drive letter.
  It will then copy relevant files from the CD, update them to the new
  version, and create a desktop object for the IDE associated with this
  version of the compiler.

  Update your CONFIG.SYS to include the BIN.OS2 directory in your
  LIBPATH, and optionally in your PATH.

  Finally, run either vcl200.cmd or vcl201.cmd to update the VCL source
  code from Borland Delphi to be compatible with VP and OS/2. Running
  this script requires that you have the Delphi 2 CD-ROM available; run
  vcl200.cmd if you have Delphi v2.00 and vcl201.cmd if you have the
  updated Delphi v2.01. If you do not know which version you have, you
  can check the timestamp of the files; for v2.00 the time is 2:00 and
  for v2.01 it is 2:01.

  When you have completed the above steps, you can delete all .CMD and
  .UPD files in the directory; they are no longer needed.

  To compile and run your Delphi programs under OS/2, please review the
  Important Notes section of this document.


New features in Virtual Pascal 1.99
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  - Full support for the AnsiString (long string) type with automatic
    garbage collection.  Strings are defined as AnsiString in the new
    {$H+} state, and as ShortString in $H-.  For full information about
    the capabilities of long strings, please refer to the Delphi 2
    documentation.

  - All constant string expressions are evaluated using long strings.
    For example, this means that if you initialise a PChar typed
    constant with a string expression, it will not be truncated to 255
    characters as it was in previous versions of VP/2 and is in Borland
    Pascal and Delphi 1.0.

  - New compiler directives:
      $H        - Huge strings
      $J        - Writable typed constants
      $Win32    - Win32 compatibility for Open32.
    Please refer to the IDE online help for details.

  - Unit aliases provide Delphi 1.0 and Delphi 2.0 compatibility.  A new
    entry field on the compiler options page is used for this purpose.
    In this entry field, enter
      Wintypes=Windows;WinProcs=Windows
    to allow Delphi v1 programs (which have WinTypes and WinProcs in
    the Uses clause) to be compiled using VP/2, where the Windows unit
    contains all references to the Windows system.

  - Support for the IN part of a program or library uses clause, such as
    "Uses
      myform in 'c:\delphi\myform.pas'"

  - Initialized variables, such as
    var
      xyz : Integer = 0;

  - The 'PACKED' reserved word can be used with records, classes or
    object types to override the $AlignRec+ state.

  - New memory manager interface:
    - A new TMemoryManager type, defining the entry points for GetMem,
      FreeMem and ReallocMem is introduced.  Two new functions,
      SetMemoryManager and GetMemoryManager are available for
      retrieving and setting the current memory manager.
    Three new functions:
    - AllocMemCount, which returns the number of times memory has been
      dynamically allocated, and
    - AllocMemSize, which returns the number of bytes of memory
      currently allocated on the heap.  The Memused function of the
      VPUtils unit should no longer be used.
    - ReAllocMem, which resizes a dynamic memory block.
    Changed interface:
    - The FreeMem procedure no longer requires an optional second
      argument specifying the size of the memory block allocated.
    - If the HeapError function returns 1 (return nil), this is treated
      as if it returned 0, which causes an EOutOfMemory exception to be
      raised or run-time error to occur.

  - New functions in the System unit:
    Finalize, Initialize, StringOfChar, UniqueString.

  - In addition to Val, Rename, Assign, AssignFile, Read, ReadLn,
    Write, WriteLn that were supported in previous versions of VP & BP,
    the following standard functions can now accept PChar parameters in
    place of string arguments:
      ChDir, MkDir, RmDir.

    Also all mentioned routines can accept nil PChar values, which are
    treated as empty strings.

  - Delphi style units are changed to use long strings instead of short
    ones:
      - SysUtils, Classes, TypeInfo.

  - In the {$Win32+} state the compiler automatically converts resource
    files from Windows 3.x or Windows 95/NT format to OS/2 format. This
    process includes all Delphi form (.DFM) files as well. The following
    types of resources are converted:
      - Bitmap
      - Icon
      - Cursor
      - Icon group
      - Cursor group
      - String table
      - RCDATA.

    In the {$Win32+} state the compiler treats the StdCall standard
    procedural directive to be equivalent to cdecl. This is because
    Open32 uses the C calling convention for all API and callback
    functions, whereas everywhere in Delphi 2 VCL source all system
    and callback function are declared as stdcall. The {$StdCall+}
    directive can still be used to declare procedures or functions that
    have got the StdCall calling convention.

  - New VCL compatible units that use IBM Open32 library are available:
      Forms, Controls, Graphics, Menus, StdCtrls, ExtCtrls, Dialogs,
      FileCtrl, Grids, Tabs, Mask, Clipbrd, Printers, Outline, Buttons.

  - Changes:
    - The $P compiler directive is made local.
    - New version conditional symbol VER20 is defined.  VER11 is not
      defined.

System requirements
~~~~~~~~~~~~~~~~~~~
  OS/2 v3.0 with Open32 installed, or OS/2 v4.0.

  Unfortunately, the Open32 library is very raw (to put it mildly) and
  dead slow.  A large number of problems have been reported to IBM by
  the fPrint development team, with the first bug reports sent to IBM 9
  month ago. Most of the problems are either not fixed or returned as
  permanent restrictions, and we have stopped hoping for the problems to
  resolved in a timely fashion.

  IBM are solving a few problems in every fixpack however, and it may be
  that they eventually solve some of the critical ones as well, such as
  the speed issues and the problems with font translation, font clipping
  and bitmap drawing.  As of FixPack 29, this has not yet happened -
  when we first started working with IBM, we hoped that FixPack 17 would
  solve most of our problems <vbg>


Important notes
~~~~~~~~~~~~~~~
  - All VCL programs should be compiled in the {&Delphi+, H+, Win32+}
    state.  The VCL units are not supplied in precompiled form, and you
    must compile them before you can compile your Delphi programs.

  - To get started, set up the Directories dialog as follows (only
    relative paths are specified; you can use full paths once you know
    where you have installed the software):
      Add OUT.OS2 to the Output box
      Add SOURCE\RTL;SOURCE\VCL to the Include box
      Add SOURCE\VCL;SOURCE\OPEN32;SOURCE\RTL to the Units box
      Add LIB.OS2 to the Library box
      Add your Delphi LIB directory to the Resource box

  - The OPEN32 conditional symbol should be defined when compiling the
    VCL source code.

  - You can use ExePack 2 (Options|Linker page) when linking Open32
    programs.  Open32 is only available in Warp 3 and 4, which both
    support this superior kind of packing.  The IDE and compiler DLLs
    have been compressed using this method.

  - Hard PM debugging mode should be used for debugging.
    (Options->Debugger->Use Hard PM Mode)

  - The Options|Directories|Units directories should include the path
    to the SOURCE\SAMPLES directory of Delphi 1 or Delphi 2.

  - The Options|Directories|Resource directories should include the path
    to the LIB directory of Delphi 1 or Delphi 2, or the resources used
    by the units will not be found.

  - Various precompiled units (System, VpSysLow, Windows, etc) are
    placed in the OUT.OS2 directory.  This directory must be included in
    the UNITS directory list, or be the output directory.

  - In some cases while compiling Delphi 2 code, indirect unit
    references to the Menus unit may be encountered. Just add the Menus
    unit to the interface uses clause of the unit where the error
    occurs.

  - The File Open dialog does not support multiple wildcards; this makes
    it slightly painful to find the .DPR files that are the main files
    for Delphi projects.  We're considering our options :)

  - The registry server (RSRV) on OS/2 v 4.0 and OS/2 v 3.0 has a bug:
    Each time an Open32 program is loaded into a debugger (or just
    loaded on some machines!), RSRV crashes with an access violation. To
    work around this problem insert the following statement into
    CONFIG.SYS:

    RUN=D:\OS2\SYSTEM\RSRV.EXE, where D: is OS/2 boot drive.

    This bug, which has not been acknowledged by IBM and thus will
    probably not be fixed, also means that your users may have to add
    this line to run your programs.  To avoid a reboot, you can start
    RSRV by typing

    START RSRV

    on the command line as well.

  - The ComCtrls unit supplied by Delphi 2 is not supported.  It
    implements all the Win32 specific controls such as TTabbedNotebook,
    TRichEdit, etc, and these are not supported by Open32, nor does IBM
    plan any support for these controls.  An alternative name for
    Open32, Close16, was suggested by one of our customers as more
    appropriate.
    To raise the chances of your program working in OS/2, try to use
    only the controls that are available in the 16-bit version of
    Delphi.


Examples
~~~~~~~~
  In the EXAMPLES subdirectory, a few examples may be found.

  The TESTVCL example, located in the EXAMPLES\TESTVCL directory, has
  TESTVCL.DPR as its main file.  The DPR extension means Delphi Project
  and is the default extension for the main file in Delphi programs.
  This example demonstrates a large number of different Delphi controls,
  and compiles and runs both with Delphi 1, Delphi 2 and VP/2.

  The final executable, which is about 250kB in size, also demonstrates
  quite well some of the problems in Open32.  Compared to how the program
  looks and works in Windows, the Open32 version has severe problems
  with speed, with the way colours are handled, and with various control
  problems.  For example, the drop-down combo boxes do not drop back up
  again once they have been dropped down.  We have used this program as
  an example with IBM, demonstrating how various bits of Open32 are
  broken, with limited success.


  The TIMETEST example, located in the EXAMPLES\TIMETEST directory,
  draws a simple form with three labels on it, and updates these on every
  IDLE message.  As with VCLTEST, this example compiles and runs, but
  does not quite live up to its Windows counterpart.  On my PPro200, the
  Win32 executable updates the labels about 450 times per second; the
  OS/2 version manages 48 updates per second.

  Also, in the OS/2 version the text in the various labels is clipped in
  various degrees.  According to the IBM labs, this is because "the code
  written to perform this operation does not conform to standard Windows
  coding practice".  Anyway, it can be worked around by making the
  labels a bit bigger in Delphi, and turning off AutoSize.


Support and contact
~~~~~~~~~~~~~~~~~~~
  No support is offered for this product, although we are interested if
  you find bugs in the compiler or linker.  Please report any problems
  by e-mail to vpascal@ibm.net.

  We are also interested to hear about it if you find a use for this
  product, and actually manage to build a program you publish.


Licence
~~~~~~~
  This product comes under the licence of Virtual Pascal for OS/2, which
  you already must own in order to install it.  This means that you are
  entitled to selling and publishing any programs you build with it.




  We wish you all the best of luck!

  The Virtual Pascal Development Team


