
   IBM Books
   
   
                        IBM VISUALAGE SMALLTALK README
                                       
   
   
   
   
   
     _________________________________________________________________
   
Table of Contents

   
   _Welcome to VisualAge Version 5.5.1_
     * Important information about Version 5.5.1
     * Late-breaking news, technical tips, and product updates
          + VisualAge Smalltalk Migration Guide
          + Product Changes
          + Additional sources of information
     * Version 5.5.1 files and installation
          + Version 5.5.1 Files
          + Installation instructions for development systems
     * Product Enhancements
          + EMSRV Support
          + RMI support for JDK 1.3 (ULC is still on JDK 1.2)
     * Documentation changes
     * Component fixes
          + APARs
          + Problems found by other sources
     * Components and Features
          + AppBuilder
          + Base
          + Database
          + EMSRV
          + Help
          + Install
          + Object Extender
          + OLE
          + Packaging
          + Server
          + Translations
          + ULC
          + Web Connection
          + XML
            
   
   
   _Disclaimer_
   
   
   
     _________________________________________________________________
   
                     WELCOME TO VISUALAGE VERSION 5.5.1
                                       
   
   
   VisualAge Smalltalk Version 5.5.1 includes all the function of
   VisualAge Smalltalk Version 5.5 plus several new features and product
   fixes. This file contains information about the VisualAge Smalltalk
   Version 5.5.1 products.
   
   
     _________________________________________________________________
   
Important information about Version 5.5.1

   
   
   For VisualAge Smalltalk Version 5.5.1, you do not need to install
   VisualAge Smalltalk Version 5.5 before you install Version 5.5.1.
   Version 5.5.1 determines if Version 5.5 is installed on you machine as
   does one of the following:
     * If Version 5.5 was previously installed, the software is upgraded
       to Version 5.5.1. The versoin 5.5.1 code is merged into the
       Version 5.5 manager.
     * If Version 5.5. was not previously installed, a full software
       install Version 5.5.1 is performed.
       
   
     _________________________________________________________________
   
Late-breaking news, technical tips, and product updates

   
   
   Please refer to the VisualAge Smalltalk web page 
   (http://www.software.ibm.com/ad/smalltalk)for technical
   information, including tips, and product updates made after this
   product release. The web page also includes information about
   Education, Services, and Support as well as hints and tips for using
   VisualAge Smalltalk. You can also link to the ftp site for product
   updates from the Support section. You can also get to the VisualAge
   Smalltalk web pages by going to the IBM web page  (http://www.ibm.com) and 
   searching for "VisualAge Smalltalk" in document titles.
   
   You can download the latest product updates from the VisualAge
   Smalltalk service ftp site (ftp://ftp.software.ibm.com/ps/products/visualage/fixes).
   
  VisualAge Smalltalk Migration Guide
     
   If you have a version prior to VisualAge Smalltalk Version 5.5
   installed, please refer to the Migration Guide for important
   information before using VisualAge Smalltalk Version 5.5.1. The
   Migration Guide is installed with the VisualAge Smalltalk Client and
   is also available on the VisualAge Smalltalk web page.
   (http://www.software.ibm.com/ad/smalltalk)

   
  Product Changes
     
   VisualAge Smalltalk Enterprise has undergone some changes. Your
   feedback regarding these plans and directions is very important to us.
   Send comments to IBM vaweb@us.ibm.com
   
   
          
   _VisualAge Smalltalk Server _
          VisualAge Smalltalk Server, the runtime environment for
          deploying server applications, is now included with VisualAge
          Smalltalk Server Workbench at no additional charge. There is no
          longer a runtime fee required to deploy VisualAge Smalltalk
          server applications on NT, Windows 2000, OS/2, Sun Solaris, or
          AIX.
          
   _RPC _
          The RPC Communications feature has been identified as an
          obsolete feature. It is still shipped and supported in this
          version of VisualAge Smalltalk, but it will be removed in the
          next version.
          
   _IMSSimulationSystem _
          The IMSSimulationSystem feature has been identified as an
          obsolete feature. It is still shipped and supported in this
          version of VisualAge Smalltalk, but it will be removed in the
          next version.
          
   
   
  Additional sources of information
    
   
    VisualAge Resource Catalog
    
   
   
   The following applies to VisualAge Smalltalk Version 5.0 and later.
   The VisualAge Partner Catalog describes VisualAge product offerings
   available from IBM and IBM Business Partners participating in the IBM
   VisualAge Object Connection Partners in Development program. The
   VisualAge Partner Catalog includes links to Object Connection partner
   companies home pages, so you can find out the details of their
   VisualAge-enabled products. Bookmark this valuable web site and visit
   often to see the latest offerings from Object Connection members. The
   VisualAge Smalltalk Partner Catalog can be linked to at
   http://www.software.ibm.com/ad/visage/rc/ . You can also access it
   from the Help menu of the VisualAge Smalltalk System Transcript or
   Organizer.
     _________________________________________________________________
   
Version 5.5.1 files and installation

   
   
   VisualAge Smalltalk Version 5.5.1 is a refresh to fix problems
   reported against Version 5.5 of VisualAge Smalltalk. Version 5.5.1
   includes fixes to customer reported APARs as well as problems reported
   by other sources. It also provides support for EMSRV 7.0 and JDK 1.3.
   
   Version 5.5.1 is packaged according to client, manager, or server
   runtime installation. The files are further packaged according to the
   target operating system.  You can download the files from the VisualAge Smalltalk
   service ftp (ftp://ftp.software.ibm.com/ps/products/visualage/fixes)

   
  Version 5.5.1 Files
  
   
   _Operating System_ _Component_ _Download file_ _Size (MB)_ 

_Windows_
        
   Client va551_cw.zip 67
   Manager va551_mw.zip 61
   Server Runtime va551_sw.zip


 _OS/2*_
      
   Client va551_co.zip 63
   Manager va551_mo.zip 61
   Server Runtime va551_so.zip 61 

_AIX_
      
   Client va551_ca.zip 70
   Manager va551_ma.zip 60
   Server Runtime va551_sa.zip 61 

_Sun_
    
   Client va551_cs.zip 55
   Manager va551_ms.zip 61
   Server Runtime va551_ss.zip
   
_HP_
      
   Client va551_ch.zip 73
   Manager va551_mh.zip 62 

_Linux_ Manager va551_ml.tar .47 
_HP_ Manager va551_mn.zip .04 


_Note:_*On OS/2, the Version 5.5.1 files must be
   unzipped to an HPFS drive because the Version 5.5.1 files contain long
   file names. If the files are unzipped to a FAT driver,the unzip
   program will not give you any error messages but when you run the
   installation program it will return errors.
   
  Installation instructions for development systems
  
   
   
   There are two pieces to the installation of the VisualAge Smalltalk
   Version 5.5.1 for development environments: the library manager and
   the client. You must install both the Version 5.5.1 library manager
   and the client. You should install the library manager first.
   _Note:_If you have previously installed VisualAge Smalltalk Enterprise
   Version 5.5, the directories icsrun, icspkg, and image will not be
   overwritten. However, the contents of other directories may be
   overwritten. You should backup any files you may need from the other
   VisualAge Smalltalk directories.
   
   You can install the Version 5.5.1 manager and client in a team
   development environment or as a standalone installation.
   
   
          
   _Team development environment _
          To install VisualAge Smalltalk in a team development
          environment, a system administrator should install the library
          manager on a network attached server computer. The individual
          developers can then install the client code locally on their
          machine and connect to the library manager using EMSRV.
          
   _Standalone _
          If you are working independently of other developers you can
          install both the library manager and the client code on one
          machine. It is recommended that you install the library manager
          before installing the client. If you uninstall the products,
          uninstall the client and then the library manager.
          
   
   
   _To obtain Version 5.5.1, follow these steps:_
    1. Download the appropriate files from the VisualAge Smalltalk
       service ftp site (ftp://ftp.software.ibm.com/ps/products/visualage/fixes)
       to a temporary directory. _Note:_On OS/2, files
       must be unzipped to an HPFS drive because the Version 5.5.1 files
       contain long file names. If the files are unzipped to a FAT
       driver, the unzip program will not give you any error messages but
       when you run the installation program it will return errors. For
       Server Runtime installation, see the platform instructions under
       Installing VisualAge Smalltalk.
    2. Unzip the Version 5.5.1 files using whatever option your unzip
       program provides to restore the subdirectory structure of the
       Version 5.5.1 file. Be sure that your unzip program restores the
       files with the same case that they were zipped with in the Version
       5.5.1 file, or use whatever option your unzip program provides to
       restore the case of the zipped Version 5.5.1 files. For example:
          + Winzip
            
            Check the _Use File folders_ option to restore the file
            directory structure of the zipped file.
          + Pkunzip
            
            Use the -d option to restore the file directory structure of
            the zipped file.
		pkunzip -d va551_cw.zip
          + Info-ZIP -- Info-ZIP is available for all VisualAge Smalltalk
            platforms. See Info-ZIP FTP site .
            
            Info-ZIP restores the directory structure by default.
		unzip va551_cw.zip
          + Untar
		tar -xvf va551_ml.tar
   
   
   
   _Before installing Version 5.5.1, follow these steps:_
    1. If EMSRV is running out of the directory to be updated, stop EMSRV
       prior to installing Version 5.5.1. Use the File I/O option to
       update the library manager executables.
    2. Stop any running VisualAge Smalltalk images.
       
   
   
    Installing VisualAge Smalltalk
    
   
   
   For installation information, see cd_m\doc\instgd.htm or
   cd_c\doc\instgd.htm in the temporary directory where you extracted the
   manager or client file. To install VisualAge Smalltalk, follow the
   instructions for your specific platform.
   
   
          
   _Windows _
          _Note:_On Windows NT or Windows 2000, logon as a user that is
          in the Administrator group. To install on Windows, from the
          temporary directory where you downloaded and extracted the
          files from the Version 5.5.1 zipped file, do the following:
          
         1. Change your current working directory to the manager or
            client subdirectory of the temporary directory:
               o cd_m
               o cd_c
         2. Change directories:
		cd install_w
         3. Run setup
            
   
          
          To install Server Runtime, do the following:
          
         1. Create a directory to install VisualAge Smalltalk into on
            your machine. For example:
		d:
		mkdir d:\vast55
		mkdir d:\vast55\server
         2. Change directories to the directory where you will install
            VisualAge Smalltalk. For example:
		cd d:\vast55\server
         3. Unzip the server runtime files as follows:
		unzip va551_sw.zip
        
   
          
   _OS/2 _
          To install on OS/2, from the temporary directory where you
          downloaded and extracted the files from the Version 5.5.1
          zipped file, do the following:
          
         1. Change your current working directory to the manager or
            client subdirectory of the temporary directory:
               o cd_m
               o cd_c
         2. Change directories:
		cd install_o
         3. Run install
            
   
          
          To install Server Runtime, do the following:
          
         1. Create a directory to install VisualAge Smalltalk into on
            your machine. For example:
		d:
		mkdir d:\vast55
		mkdir d:\vast55\server
         2. Change directories to the directory where you will install
            VisualAge Smalltalk. For example:
		cd d:\vast55\server
         3. Unzip the server runtime files as follows:
		unzip va551_so.zip
        
   
          
   _Unix _
          To install on Unix, from the temporary directory where you
          downloaded and extracted the files from the Version 5.5.1
          zipped file, do the following:
          
         1. Change your current working directory to the manager or
            client subdirectory of the temporary directory:
               o cd_m
               o cd_c
         2. Change your current working directory to a
            platform-appropriate subdirectory:
               o install_a for AIX
               o install_h for HP-UX
               o install_s for Sun Solaris
         3. From the shell command line, run xterm -sb -e ./setup&
            
   _Note:_On some Unix platforms, problems have been reported on the
          Select Features screen. Sometimes the Next button is not
          enabled due an error in sychronization of the features. To
          correct this problem, select the Back button and then select
          the Next button. The Next button on the Select Features screen
          should then be enabled. _Note:_The installer writes
          installation status messages to its stdout stream. These
          messages will appear within the dtterm or xterm where the
          installer was started.
          
          For Server Runtime on UNIX, the files are tarred to absoluate
          paths. You must decompress and untar them. To install Server
          Runtime, do the following:
          
        
                
        _AIX _
                Decompress and untar as follows:
                
		mv va551_sa.taz va551_sa.tar.Z;zcat va551_sa.tar.Z|tar -xvf -

        
                
        _Sun _
                Decompress and untar as follows:
                
		mv va551_ss.taz va551_ss.tar.Z;zcat va551_ss.tar.Z|tar -xvf -

   
          
   _Linux _
          To install a manager on Linux:
          
         1. You should have already downloaded the Linux manager code
            va551_lm.taz to a temporary directory.
         2. Move the Linux manager code into the /opt subdirectory tree:
		mv va551_lm.taz va551_lm.tar.Z;zcat va551_lm.tar.Z|tar -xvf  -
         3. Do a VisualAge Smalltalk Manager install on one of the
            supported platforms (Windows, OS/2, AIX, HP-UX, Solaris) to
            populate the manager file.
         4. FTP the <varoot>\manager\mgr55.dat file to the
            /opt/IBMvast/5.5/manager directory on your Linux machine.
            
   
          
   _NetWare _
          To install a manager on NetWare:
          
         1. You should have already installed the executables by
            downloading the NetWare manager code, va551_nm.zip, and
            unzipping it into a temporary directory.
         2. Copy emsrv.nlm into the SYS:\SYSTEM directory on your NetWare
            file server.
         3. Install VisualAge Smalltalk Manager on one of the supported
            platforms (Windows, OS/2, AIX, HP-UX, Solaris) in order to
            populate the VisualAge Smalltalk Manager file.
         4. Copy the <varoot>\manager\mgr55.dat file to its desired
            location on your NetWare file server.
            
   
   
   For further instructions on installing and getting started with
   VisualAge Smalltalk, please see the VisualAge Smalltalk Installation
   Guide and the VisualAge Smalltalk Getting Started Guide installed with
   the Information Center for VisualAge Smalltalk. If you would prefer
   the documentation in PDF format, please see our VisualAge Smalltalk
   web page (http://www.software.ibm.com/ad/smalltalk)
   
    After installing VisualAge Smalltalk Version 5.5.1
    
   
   
   
   
   The Version 5.5.1 installation automatically merges the Version 5.5.1
   code into the Version 5.5. manager. However, you must move any
   work-in-progress from the existing Version 5.5. mananger to the new
   Version 5.5.1 manager. If you had previously installed Version 5.5, 
   before you use VisualAge Smalltalk Version, follow these steps:
   5.5.1, do the following:
    1. Version and release all open editions of classes and
       subapplications, and version the applications.
    2. Save to files any text from workspaces or from the Transcript
       window that you want to keep.
    3. After you have completed the install, you can then load your versioned
       work from the new Version 5.5.1 manager into the VisualAge
       Smalltalk Version 5.5.1 client.
       
   
   
    Unlocking products
    
   _Note:_Any features that were unlocked in the VisualAge Smalltalk
   Enterprise Version 5.5 image must be unlocked in the VisualAge
   Smalltalk Enterprise Version 5.5.1 image. Ensure that the unlock tool
   is pointing to the new VisualAge Smalltalk Enterprise Version 5.5.1
   ini file in the image551 directory.
   
   After you install, you must unlock VisualAge Smalltalk Enterprise, and
   any features you installed. All products are initially installed as
   evaluation products. When you purchase a product, you receive a key
   which you use to unlock the evaluation product. If you load an
   evaluation feature into your image, even if you unlocked VisualAge
   Smalltalk Enterprise, your image will become an evaluation image. When
   you unload the evaluation feature, your image will still be an
   evaluation image.
   
   For this reason, _be sure to unlock all features you have purchased
   before you load them into your image_. If you want to try a feature
   that you have not purchased, be sure to make a backup copy of your
   image file (abt.icx) before you load the evaluation feature. Then, try
   the feature. When you are through, you can restore the image you
   backed up before you loaded the evaluation feature.
     _________________________________________________________________
   
Product Enhancements

   
   
  EMSRV Support
  
   
   
   The major enhancements in EMSRV 7.0 (VisualAge Smalltalk Enterprise
   5.5.1) since EMSRV 6.24 (VisualAge Smalltalk Enterprise 5.5) are:
     * Support for FAT32 volumes on Windows 2000
     * Support for PAM authentication on Linux and Solaris platforms
     * Support for DCE authentication on AIX platforms
     * Support for NetWare 5.1
     * Support for Red Hat Linux 6.1 and 6.2
     * Support for AIX 4.3.3
     * Support for authentication using Active Directory Services on
       Windows 2000
     * Support for cross-domain authentication on Windows NT
       
   
   
  RMI support for JDK 1.3 (ULC is still on JDK 1.2)
  
   
   
   The RMI in Server Smalltalk will run under JDK 1.3, using the same
   techniques that were required for JDK 1.2. However, ULC is still at
   the JDK 1.2 level.
     _________________________________________________________________
   
Documentation changes

   
   
   Documentation changes for VisualAge Smalltalk Version 5.5 include:
     * Hardcopy documentation is no longer provided. All manuals are
       online documentation in HTML format, which you can view with a Web
       browser such as Netscape Navigator or Microsoft Internet Explorer.
       All manuals are also provided in PDF format at the VisualAge
       Smalltalk web page (http://www.software.ibm.com/ad/smalltalk).
     * The VisualAge Smalltalk Search page now allows you to select from
       different generic areas from which to narrow your search. For
       example, you can choose the Database Guide to search both the
       Database Guide and the Database Help. There are also pushbuttons
       to allow you to select the genre of books you would like to
       search:
          + Select VisualAge items
          + Select Smalltalk items
          + Select Server items
     * The following documents are new:
          + VisualAge Smalltalk Server Smalltalk Guide, which includes
            information formerly in the VisualAge Smalltalk Server Guide.
          + VisualAge Smalltalk Advanced Database Guide, which includes
            information about the Advanced Database feature for VisualAge
            Smalltalk .
     * The following documents have had significant format changes:
          + All part reference information was put into the VisualAge
            Parts Reference.
          + Server information for features was moved from the VisualAge
            Smalltalk Server Guide to the specific feature guide.
          + Help information for specific features was moved into the
            HTML manual for that feature.
     * The following documents have been updated for Version 5.5.1
          + VisualAge Smalltalk Installation Guide
          + VisualAge Smalltalk User's Guide
          + VisualAge Smalltalk Web Connection Guide
          + VisualAge Smalltalk Server Guide
          + IBM Smalltalk Programmer's Reference
          + IBM Smalltalk User's Guide
          + VisualAge Smalltalk Part Reference
          + IBM Smalltalk Programmer's Reference
          + VisualAge Smalltalk Server Smalltalk Guide
   
   
     _________________________________________________________________
   
Component fixes

   
   
   This section documents fixes to problems reported to IBM by customers
   (APARs) and problems reported through other sources. They are listed
   by APAR number.
   
  APARs
  
   
   
   Fixes are included for the following problems found by customers. The
   problems are listed by APAR number.
   
   
   _APAR_ _IBM Defect_ _Component_ _Description_ PQ12729 9433 Base Symbol
   class should not implement this method PQ14820 9868 Appbldr Notebook
   page not enabling correctly PQ18708 10593 Appbldr Walkback when
   opening the framing spec dialog for a widget PQ22210 12060 Base Emsrv
   must be started as root on Solaris PQ22569 12077 Base Emadmin copy
   doesn't work if user is saving a part PQ26855 12759 Base Image hangs
   when displaying the float NaN PQ31529 13283 Appbldr Can remove group
   member from app even if user is manager of app PQ33662 13316 Base OLE
   object is not being cleaned up after several (1000) iterations of
   instantiating the OLE object PQ31489 13359 Base
   Triggerselectioncallback event being fired twice PQ35821 13430 Appbldr
   Performance problem in comp editor when deleting a part. PQ37355 13471
   Base Using acrobats control from smalltalk inside the "find" PQ37689
   13525 Base Resizing a container horizontally may cause button motion
   event PQ38906 13726 Base Cutting and pasting in an MLE results in
   fewer characters PQ40781 13977 SST Smalltalk RMI connection goes
   inoperable with socket in close_wait state. PQ43647 14018 SST
   Block>>#whenTimeoutInMilliseconds:do: causes ExTimeout.
   
  Problems found by other sources
  
   
   
   Fixes are included for the following problems found by IBM. The
   problems are listed by defect number.
   
   
   _IBM Defect_ _Component_ _Description_ 12779 Comm Cpic connected event
   fires twice on MVS. 13232 Nls WB: UndefinedObject DNU packager in NLS
   extension to packager. 13632 Web AbtWebSamplesSelectionColumnPage
   sample is not working. 13656 Web Connection External sample files not
   being installed on OS/2. 13793 Base Update web links from Help. 13823
   Xml XML - Unload problems. 13827 Base F1 help error on load/unload
   features dialog. 13852 Comm Code page field improperly initialized for
   comm parts on UNIX. 13957 Xml XML - AbtDOMConstants contain nil
   values. 13200 Base Missing text for packager messages 688 and 689.
   13961 SST RMI Wizard: Need to be stricter in checking ST method names.
   13963 Xml XML - SAX namespace #getUri: needs to support inheritence.
   13964 Xml XML - Serialization bugs and improvements. 13968 SST RMI
   Wizard: Cannot always create stubs to VAJ repository. 13975 Xml
   AbtXmlObjectCache should be cleared in packaged images. 13978 SST RMI
   Wizard: need better message when can't find interface. 13979 Comm
   SciHostEnt method calls #address: rather than #addr: 13981 Base
   Creating a ScaledDecimal from a String fails in some instances 13982
   Xml XML invalid attribute values not reported. 13987 SST RMI Wizard:
   wizard just exits if user is not open-edition owner. 13988 SST RMI
   Wizard: Space appended to name of array return type. 13991 Base
   Implement additional ANSI Smalltalk protocol. See ANSI Smalltalk
   support. 13998 Comm
   SciSocketManager>>#selectRead:write:except:timeout: prologue. 13999
   Comm Upgrade to EMSRV 7.0. 14001 Base Update base code to V5.5.1.
   14002 ULC Gen Lang MPR fr Unicode generates Pre-R3.0 mpr. 14011 Comm
   #callLoopingSendWith:with:with:with: can get stuck on AIX. 14017 Xml
   Optimizations to #abtXmlPrintString based upon customer feedback.
     _________________________________________________________________
   
Components and Features

   
   
   The following sections list some important information about some of
   the components and features. For the latest product information,
   please refer to the VisualAge Smalltalk web page .
   
  AppBuilder
  
   
   
    Setting your monetary symbols in UNIX
    
   
   
   On UNIX, make sure your LC_MONETARY locale setting contains a
   non-empty mon_decimal_point entry. On some machines, mon_decimal_point
   may be empty for the C locale.
   
   For example, if you wish to change to the en_US locale, set your LANG
   environment variable to en_US before starting VisualAge Smalltalk with
   the ksh command. For example:
	export LANG=en_US

   
   
   You can check the value of mon_decimal_point with the following
   command:
	locale -k LC_MONETARY

   
   
   The output should look like the following:
	int_curr_symbol="USD "
	currency_symbol="$"
	mon_decimal_point="."
	mon_grouping="3"
	mon_thousands_sep=","
	positive_sign=""
	negative_sign="-"
	int_frac_digits=2
	frac_digits=2
	p_cs_precedes=1
	p_sep_by_space=0
	n_cs_precedes=1
	n_sep_by_space=0
	p_sign_posn=1
	n_sign_posn=1
	debit_sign="DB"
	credit_sign="CR"
	left_parenthesis="("
  	right_parenthesis=")"

   
   
    On AIX, turn NumLock off when dropping parts
    
   
   
   Be sure that your numlock key is turned off if you are using the
   composition editor. The numlock will prevent parts from being dropped
   on the Composition Editor.
   
    On UNIX platforms, "X Error: BadWindow" message appears for Slider part
    
   
   
   Each time the Slider part is repainted the message X Error: BadWindow
   (invalid Window parameter) is printed in the xterm window from which
   VisualAge Smalltalk was launched.
   
   The Slider part still functions normally.
   
  Base
  
   
   
    On Solaris version 8, UNIXProcess class>>#system: call may have problems
    
   
   
   On Solaris, if you are encountering odd behavior when using the
   UNIXProcess class>>#system: call to execute C shells, your problem
   might be that your call is using the wrong version of the libcurses.so
   library. When you start Smalltalk with the abt shell script, the
   LD_LIBRARY_PATH is set so that /usr/ucblib is searched before the
   /usr/lib path. Many Solaris executables will not work correctly if
   they are linked to /usr/ucblib/libcurses.so at runtime. To workaround
   this problem, in /opt/IBMvast/5.5/bin, create a link named
   libcurses.so.1 that points to /usr/lib/libcurses.so.1.
   
    Clients and Managers should be in synch with each other
    
   
   
   You should install the same features on the VisualAge Smalltalk Client
   that you install on your Visual Smalltalk Manager. If you install
   features on the VisualAge Smalltalk Manager and do not have these same
   features installed on the VisualAge Smalltalk client, you will still
   see these features listed in the Load/Unload Dialog window of the
   VisualAge Smalltalk client. However, if you load these features on the
   VisualAge Smalltalk Client, VisualAge Smalltalk will not install the
   required code and they may not function properly due to missing files.
   Error messages such as unresolved strings (because of the missing cat
   files), missing ICs, missing sample files, and anything else that gets
   copied as part of the client install of that feature may then appear
   in the System Transcript window.
   
    On MVS, INIs are optional for packaged applications. All other platforms,
    INIs are required for packaged applications
    
   
   
   On MVS, an .ini file is optional. On all other platforms, an .ini file
   is required. The .ini file may have the same name and be in the same
   directory as your executable (on Unix, the executable is es or esnx).
   The .ini file can also have the same name and be in the same directory
   as your .icx or .ic file.
   
   In addition, you can specify your .ini file as a command line
   parameter. For example, you can launch your program by typing the
   following:
	abt -imyapp.icx -ini:c:\any.ini

   
   
    ANSI Smalltalk support
    
   
   
   Support for ANSI Smalltalk (see ANSI/NCITS 319-1998 Smalltalk
   Programming Language, available in PDF format from
   http://www.cssinfo.com/ncitsgate.html ) is included in this release
   of VisualAge Smalltalk Enterprise. This support greatly enhances the
   portability of Smalltalk applications between different Smalltalk
   implementations that provide ANSI Smalltalk support.
   
   All methods supporting the ANSI Smalltalk protocol are categorized as
   ANSI-API. Methods associated with ANSI Smalltalk function that are not
   complete in this release are categorized as ANSI-Unimplemented.
   
   The following restrictions with respect to ANSI Smalltalk are in force
   for this release:
    1. The following _DateAndTime_ methods are not functional:
          + _clockPrecision_ (factory method)
          + _now_ (factory method)
          + _year:day:hour:minute:second:_ (factory method)
          + _year:month:day:hour:minute:second:_ (factory method)
          + _timeZoneAbbreviation_
          + _timeZoneName_
    2. The following Exception methods are not functional:
          + _isNested_
          + _outer_
          + _pass_
          + _resignalAs:_
          + _retry_
          + _retryUsing:_
    3. The _MessageNotUnderstood_ exception class is provided, but is not
       signaled by the standard _#doesNotUnderstand:_ method.
    4. The _ZeroDivide_ exception class is provided, but is not signaled
       when a divide by zero occurs.
       
   
   
    Changes in ScaledDecimal
    
   
   
   To support the ANSI Smalltalk Standard, the following changes in the
   behavior of ScaledDecimal have been made:
    1. A ScaledDecimal literal is now supported. The format of this
       literal is:
	<integer-part>[.[<decimal-part>]]s[<scale>].
   
       
       Here are some examples of ScaledDecimal literals:
	3.4s     1274s5     0.88s     0.96s1
    2. The ScaledDecimal>>#printOn: format has been changed to match the
       format of the ScaledDecimal literal. The old format of printing
       ScaledDecimal is still available for compatibility purposes by
       using the ScaledDecimal>>#printOn:showDigits:pad: and specifying
       true for the showDigits parameter.
    3. The format of the string parameter to ScaledDecimal
       class>>#fromString: has been changed to match the format of the
       ScaledDecimal literal. The old string format is still supported
       for comparibility purposes.
    4. The ScaledDecimal>>#debugPrintOn: method has been added so that
       inspecting a ScaledDecimal object does not lose detail due to the
       new ScaledDecimal>>#printOn: format.
       
   
   
    Changes in Float
    
   
   
   To support the ANSI Smalltalk Standard, the following changes in the
   behavior of Float have been made:
   
   Additional Float literals are now supported by extending the possible
   values of the exponent character. The exponent character now has the
   following meaning:
	d - Single Precision Float
	e - Double Precision Float
	q - Quad Precision Float

   
   
   This is only a syntax change. This change does not have any effect on
   the actual Float values which continue to be represented internally in
   double precision.
   
    On Unix, timestamps show up as %r
    
   
   
   On some UNIX machines, you may see %r where you expect to see a string
   represinting a time. This will happen when your LC_TIME setting for
   your current locale contains the format identifier %r. VisualAge
   Smalltalk does not currently handle this format identifier. You can
   fix this problem in one of two ways;
    1. Change the LC_TIME definition for your desired locale. Consult the
       man pages for locale and localedef information.
    2. To enable your timestamps to appear in 24-hour format, execute the
       following code in Smalltalk:
	NlsGlobals::CurrentLCTime tFmt: '%H:%M:%S'
   
       
       To enable your timestamps to appear in 12-hour format, execute the
       following code in Smalltalk:
	NlsGlobals::CurrentLCTime tFmt: '%I:%M:%S %p'
   
   
   
    HTML Help TCP/IP requirements
    
   
   
   The HTML Help subsystem requires that TCP/IP be configured and
   functional. HTML Help will function with or without a network adapter
   as long as TCP/IP is configured properly.
   
      Windows 95, Windows 98, Windows NT, Windows ME, and Windows 2000
      
   
   
   For Windows platforms, configure TCP/IP according to your adapter
   configuration:
    1. If you are using a LAN adapter configuration, ensure the
       following:
          + You must have DNS enabled with a valid host and domain name.
          + Your LAN DNS must resolve localhost to 127.0.0.1
          + You must run connected with the LAN adapter configuration.
    2. If you are using a Dial-Up Adapter configuration, ensure the
       following:
          + You must have DNS disabled.
          + Your TCP/IP Address must be obtained automatically.
   _Note:_These configuration options will apply to all TCP/IP adapters
       even though they have only been changed for this particular
       Dial-Up adapter. You will not be able to use both LAN and Dial-Up
       unless you reconfigure.
    3. If you are running standalone, you can enable the MS Loopback
       Adapter without enabling the other two adapters.
       
   
   
      OS/2
      
   
   
   For OS/2, configure TCP/IP as follows:
    1. Enable local loopback by performing the following steps:
         1. Open the OS/2 TCP/IP folder.
         2. Open the TCP/IP Configuration notebook..
         3. View the Network page.
         4. In the listbox labelled Interface to Configure, highlight the
            item labelled loopback interface.
         5. Verify that the checkbox on the right labelled Enable
            interface is checked.
         6. With loopback interface still highlighted, verify that the
            entry field for IP address is 127.0.0.1 and that the Subnet
            Mask is empty.
    2. Verify that localhost is enabled on your system by doing the
       following:
         1. On any OS/2 command line enter ping localhost. This command
            should return some data back rather than just hang. If it
            hangs, or if it returns localhost unknown, then localhost has
            not been enabled on your system. If you are on a network,
            then make sure loopback is enabled. If you are not on a
            network, enable localhost by performing the following steps:
              1. Adding the following line after other ifconfig lines in
                 the MPTN\BIN\setup.cmd command file:
	 ifconfig lo 127.0.0.1
              2. In the TCP/IP configuration:
                   1. Go to the Configure Name Resolution Services page
                      (page 2 of Hostnames).
                   2. Add an entry to the table titled Hostname
                      configuration without a Nameserver. Set the IP
                      Address to 127.0.0.1 and the Hostname to localhost.
                      If you have a host name specified for your machine
                      on page 1 of "Hostnames" (titled Configure LAN Name
                      Resolution Services), then you must add this host
                      name as an alias while you are setting the IP
                      Address 127.0.0.1 to localhost.
                   3. Check the check box underneath the table labeled:
                      "Look through HOSTS list before going to
                      nameserver." This will enable localhost to bypass
                      any nameserver to resolve the name.
                   4. Close TCP/IP Configuration and reboot and the
                      system.
                   5. You should be able to ping localhost without being
                      connected to any network. If ping localhost still
                      hangs, remove any nameservers from the TCP/IP
                      configuration so that name resolution can be done
                      only by looking at the HOSTS list.
    3. Verify that your hostname is correct by doing the following:
          + From an OS/2 command line, enter hostname.
          + Verify that the hostname returned is the same as the one
            listed in the TCP/IP Configuration notebook on the Hostnames
            page and verify that the hostname is less than 32 characters.
    4. If any TCP/IP settings were changed, be sure to reboot OS/2 and
       restart TCP/IP.
       
   
   
    HTML Help browser setup
    
   
   
   Set up the HTML help browser setup according to your browser type:
   
   If you use Internet Explorer or Netscape with a firewall (proxies
   enabled), then you must modify the default settings for help to work
   properly.
   
      Windows -- Internet Explorer 5
      
   
   
   Set up Internet Explorer 5 as follows:
    1. Select Tools... Internet Options.
    2. Select the Connection tab.
    3. Click LAN Settings.
    4. Select the _Bypass proxy server for local addresses_ checkbox.
       _Note:_This checkbox is only available if you are using a proxy or
       socks connection and have selected the "Use a proxy server"
       checkbox.
    5. Select the Advanced button.
    6.
       
       Type localhost:49213 in the _Exceptions... Do not use proxy
       servers for addresses beginning with_ box. If you have other
       entries here, separate the new entry with a semi-colon.
    7. Click OK, then click OK again to exit the LAN Settings dialog, and
       click OK again to exit the Internet Options dialog.
       
   
   
      Windows -- Netscape 4 (Navigator)
      
   
   
   Set up Netscape 4 (Navigator) as follows:
    1. Select Edit... Preferences...
    2. Double-click Advanced in the Category tree.
    3. Click Proxies in the Advanced subtree.
    4. Click View at the Manual Proxy Configuration selection.
    5. Type localhost:49213 in the _Exceptions... Do not use proxy
       servers for addresses beginning with_ box. If you have other
       entries here, separate the new entry with a comma.
    6. Click OK, then click OK again to exit the Preferences window.
       
   
   
   If you are using a SOCKS client, be sure that 127.0.0.1 is accessed
   directly and not resolved by the SOCKS server. You can tell if your
   SOCKS client needs to be configured by using FTP. Try to FTP to
   localhost or to 127.0.0.1. If you cannot FTP, then your SOCKS client
   may need configuring. For example, the Hummingbird SOCKS client uses a
   configuration file to determine IP addresses that should be accessed
   directly. You must update this file so that 127.0.0.1 is not passed to
   the SOCKS server. To update the Hummingbird SOCKS configuration:
    1. Edit the Hummingbird configuration file SOCKS.CNF
    2. Add the line:
 	DIRECT 127.0.0.1 255.255.255.255
    3. Save the file.
       
   
   
   Depending on your SOCKS client, you may need to restart your system
   for the new settings to take effect.
   
      OS/2
      
   
   
   Set up OS/2 as follows:
    1. If you are using a SOCKS client, be sure that 127.0.0.1 is
       accessed directly and not resolved by the SOCKS server.
    2. You can tell if your SOCKS client needs to be configured by using
       FTP. Try to FTP to localhost or to 127.0.0.1. If you cannot FTP,
       then your SOCKS client may need to be reconfigured. You must also
       have the LoopbackAdapter enabled (see HTML Help TCP/IP
       requirements.)
    3. Depending on your SOCKS client, you may need to restart your
       system for the new settings to take effect.
       
   
   
  Database
  
   
   
    Double-Byte Character Set Readme
    
   
   
   For more information on double-byte character sets, see the
   Double-Byte Character Set readme, <vast55>\readme\readdbcs.htm
   
    On HP and Solaris, Library path not set up properly for DB2
    
   
   
   On HP and Solaris, the abt script file attempts to set up the shared
   library path to include DB2 if DB2 is detected. However, the Korn
   shell on HP and Solaris does not always evaluate the tilde character
   (~) so that VisualAge can set up the shared library path to include
   DB2. This causes the libraries for DB2 to not be added to the path
   correctly.
   
   To workaround this problem, you must add the DB2 libraries. You may
   want to add the one of the following examples to your profile.
	HP:   export SHLIB_PATH=/home/db2inst1/sqllib/lib:$SHLIB_PATH
	Solaris: export LD_LIBRARY_PATH=/home/db2inst1/sqllib/lib:$LD_LIBRARY_PATH

   
   
    Get schema function on Stored Procedure Specification Settings
    
   
   
   When using stored procedures with the new Oracle 8 database
   connection, the Get schema function on the Stored Procedure
   Specification Settings view only works for procedures that are not
   contained in packages. Users must manually define host variables for
   procedures that are contained in packages.
   
    Running Oracle samples
    
   
   
   To create the stored procedure used in the Oracle sample, logon to
   SQL*PLUS and use the file found in your vast\samples\oracle directory.
   For example:
    1. Logon to SQL*PLUS
	sqlplus userid/password
    2. Execute the file
	SQL> @vast\samples\oracle\sample.sql
   
   
   
    ODBC Drivers are no longer shipped with VisualAge for Smalltalk
    
   
   
   ODBC drivers are not shipped with VisualAge for Smalltalk V5.5 as they
   were with some previous versions. The drivers in previous versions
   were provided by MERANT (formerly INTERSOLV Inc.). If you need to
   obtain ODBC drivers, the DataDirect product is still available
   directly from MERANT. For more information call 800-876-3101 or visit
   http://www.merant.com/datadirect
   
   You can also check your DBRM for ODBC drivers. Most, if not all, major
   DBRMs now ship with ODBC drivers.
   
    On AIX, database features require extracting shared library
    
   
   
   Before you can run the database features on AIX, you must extract a
   shared object from the appropriate archive file. This is true for IBM
   DB2, ODBC, and Oracle databases.
   
      IBM DB2
      
   
   
   For IBM DB2, extract the file from $DB2INSTANCE/sqllib/lib/libdb2.a by
   performing the following steps:
    1. Extract the shared object
	ar -x libdb2.a
    2. Rename the extracted file libdb2.so
	mv shr.o libdb2.so
   
   
   
      ODBC
      
   
   
   For ODBC, extract from your libodbc.a file by performing the following
   steps:
    1. Extract the shared object
	ar -x libodbc.a
    2. Rename the extracted file libodbc.so
	mv libodbc.o libodbc.so
   
   
   
      Oracle
      
   
   
   For ORACLE, extract from your libclntsh.a file by perform the
   following steps:
    1. Extract the shared object
	ar -x libclntsh.a
    2. Rename the extracted file libclntsh.so
	mv clntsh.o libclntsh.so
   
   _Note:_For each of these databases, the resulting .so file must be in
   the library path (LIBPATH) in order to be located by VisualAge.
   
    Prerequisite AbtRecordStructureApp in Database Applications
    
   
   
   Some database applications will need to add a prerequisite for the
   _AbtRecordStructureApp_ application. Applications that use Database
   Parts will NOT need to add this prerequisite because the parts will
   include the _AbtRecordStructureApp_ application. If an application
   manipulates instances of any of the subclasses of _AbtRow_, they will
   probably need to add this prerequisite.
   
   If you package your application and get the error The attribute Pub
   <Attr name> does not exist at runtime, you need to include the
   _AbtRecordStructureApp_ application.
   
    On Unix, running Database Features
    
   
   
   On Unix, if you are using database features and experience a core dump
   when exiting VisualAge, comment out the _PlatformLibrary>>shutDown_
   method. An alternative solution for your packaged application is to
   execute the following code when exiting:
	System primitiveExit

   
   
  EMSRV
  
   
   
    On OS/2, STARTing EMSRV
    
   
   
   In an OS/2 environment, if EMSRV is installed under a directory name
   that contains spaces (e.g. x:\VAST55 MG\bin), attempting to invoke
   EMSRV via an OS/2 START command may fail with a SYS1041 message. For
   example, when issued from the varoot\bin directory, the following
   command:
	START EMSRV -u <userid> <password>

   
   
   may get the message SYS1041: The name EMSRV is not recognized as an
   internal or external command, operable program or batch file. To
   bypass this problem, issue the command sequence without the START:
	EMSRV -u <userid> <password>

   
   
    Using the Manager file
    
   
   
   Be sure to use the following good development practices with EMSRV:
     * Backup the manager file regularly.
     * Run library statistics utilities on a regular basis to ensure the
       integrity of the manager file.
     * Protect the manager file.
       
   
   
  Help
  
   
   
    On Solaris and HP-UX, system requirements for NetQuestion
    
   
   
   On Solaris, NetQuestion requires the following minimum values to be
   set in the /etc/system file:
	semsys:seminfo_semmni = 2048
	semsys:seminfo_semmap = 2050
	semsys:seminfo_semmns = 4096
	semsys:seminfo_semmnu = 4096
	semsys:seminfo_semmsl = 50
	shmsys:shminfo_shmmax = 6291456
	shmsys:shminfo_shmseg = 300
	shmsys:shminfo_shmmni = 300

   
   
   For HP-UX, use the System Administration Manager (SAM) to set these
   values. They are located under Kernel Configuration -> Configurable
   Parameters. Look for names like the above except only the text after
   the '_' is listed in SAM, i.e., semsys:seminfo_semmni gets mapped to
   semmni in the SAM. Verify that the values listed in SAM are greater
   than or equal to what is listed above.
   
   If you have additional indexes that exist due to the installation of
   other products that use NetQuestion, then these values may need to be
   increased. Changing these values will require a reboot of the system.
   See the system(4) man page for further information on the /etc/system
   file on Solaris.
   
   For HP-UX, there is help available inside of SAM. This is necessary
   because NetQuestion requires 9 semaphores plus 45 additional
   semaphores for every index.
   
    On UNIX, Netscape 4.7
    
   
   
   On the UNIX platform, if you use Netscape 4.7, VisualAge Smalltalk may
   not be able to bring up Netscape when you try to access the help
   system. To workaround this problem on HP and SUN, bring up Netscape
   manually before accessing the VisualAge Smalltalk Help. On AIX, bring
   up Netscape manually and type in the following URL :
	http: //localhost:49213/cgi-bin/abtwebx.exe/en_US/q/Extract/5.5/abtzva55/vast.htm

   
   
  Install
  
   
   
    On OS/2, NetQuestion install problem
    
   
   
   The NetQuestion installer on OS/2 cannot process an install script
   file that is in a directory path containing blanks or other special
   characters which require the resulting filename to be quoted. If you
   install VisualAge Smalltalk Client in a directory that must be quoted,
   the NetQuestion install will timeout without installing NetQuestion.
   To install NetQuestion manually, perform the following steps:
    1. Make <varoot>\inst your current directory.
    2. Copy the netq.iss file to a directory name that does not require
       quoting (i.e., does not contain spaces or other special
       characters).
    3. Edit the abtnq_b.cmd file.
    4. Modify the line that starts with install.exe so that it points to
       the new location of the netq.iss file.
    5. Save the abtnq_b.cmd file and execute it
       
   
   
    On AIX, set Read/Write Permissions for mgr55.dat after installing Smalltalk
    
   
   
   After installing VisualAge Smalltalk manager for AIX or VisualAge
   Smalltalk Stand Alone for AIX, if you are getting access denied
   messages, set the access parameters (Read/Write Permissions) for the
   mgr55.dat file.
   
    On AIX, create a Journalled File System before installing Smalltalk
    
   
   
   On an AIX machine, before installing Smalltalk for the first time, use
   Smitty or Smit to create a Journalled File System.
   
    On AIX, increase disk space for Smalltalk installation
    
   
   
   On an AIX machine, before installing base Smalltalk for the first
   time, use Smitty or Smit to increase the disk size to 200 Megabytes.
   
    Accessing the Smalltalk newsgroup using Netscape
    
   
   
   If you are attempting to access the VisualAge Smalltalk newsgroup (
   news://news.software.ibm.com/ibm.software.vasmalltalk ) using a
   Netscape browser, you must choose one of the following items in the
   Netscape browser's _Edit->Preferences->Advanced->Proxies_ menu:
     * Direct connection to the Internet
     * Manual proxy
       
   
   
   If you have selected an autoproxy from this menu, your attempt to
   access the VisualAge Smalltalk newsgroup will fail.
   
  Object Extender
  
   
   
    Serializing Business Objects for server applications
    
   
   
   The _dataObject_ attribute of a BusinessObject may be out of synch
   with the current version's data. Code that looks like the following:
	aBO dataObject

   
   
   should be changed to the following code:
	aBO dataObject
                pullDown: aBO;
                yourself

   
   
   The above example code ensures that the _dataObject_ has been
   synchronized with the Business Object.
   
    VAP suppresses exception and does not get passed to the application
    
   
   
   Database Errors are wrapped into _VapExceptions_ which can be accessed
   by various helper methods on the _Signal_ class. The following code is
   an example of the _#asVapAbtError_ method:
	[VapDepartmentHome singleton findByPrimaryKey: aKey] when:
   	VapExceptions::ExVapException
     	do: [:sig||abtError| (abtError := sig asVapAbtError) rc = 100
           ifTrue: [self log: 'Department not Found: ',abtError errorText]
           ifFalse: [sig signal "This handler is finished - re-signal for other
 	handlers"]].

   
   
    Oracle Drop does not work in certain cases
    
   
   
   When using an Oracle database, the primary key must be deleted before
   the table can be deleted.
   
    Pessimistic locking must be set in subclass if hierarchy exists
    
   
   
   If there is a class hierarchy, and pessimistic locking is desired, it
   must also be set in the subclass or it will not work correctly. For
   example, an _Account_ class could have the subclasses _SavingsAccount_
   and _CheckingAccount_. Pessimistic subclassing would then need to be
   set in those two subclasses.
   
  OLE
  
   
   
    Copying from Windows Explorer into an OLE Client part
    
   
   
   Use copy and paste to share OLE objects between the Windows Explorer
   and an OLE Client part. Dropping an OLE object that was dragged from
   the Windows Explorer onto an OLE Client part does not work.
   
  Packaging
  
   
   
    XD packaging of non-MVS leaf ICs which use MPRs at runtime
    
   
   
   Using the Packager UI (Modifiy Instructions :: Applications and ICs),
   you must manually add _AbtNlsCfsSupportApp_ to the image that you are
   packaging as follows:
    1. Select _AbtNlsCfsSupportApp_ in the left pane.
    2. Press the _>>_ button. (It will be highlighted. There are two of
       these buttons. You want to press the one on the left that is below
       the left and/or center panes).
       
   
   
  Server
  
   
   
    IIOP PingPong examples fail with an object other than a String
    
   
   
   When running the IIOP PingPong examples you must pass a type that
   conforms to the CORBA Any type interface. Typically, Strings are used
   as the argument representing @anAnyType when sending the method
   _SstPingPongIIOP>>start: @anInteger with: @anAnyTYpe_. Passing
   Smalltalk Integers and Floats as arguments will cause the example to
   fail because CORBA does not represent these as objects, and therefore,
   they do not conform to the Any interface.
   
    Using XD Interactive Debugger over TCP/IP with no nameserver
    
   
   
   When trying to use the interactive debugger, if you are getting the
   error EHOSTNOTFOUND or EADDRNOTAVAIL on the runtime side, the problem
   may be that your runtime machine cannot resolve the dotted TCP/IP
   address of your development machine. You can work around this problem
   by adding an entry to the hosts file on the runtime machine for your
   development machine.
   
    RMI Wizard considerations
    
   
   
   The RMI Wizard adds the following instance methods to all mapped
   classes:
   
   
          
   _sstRmiClassName _
          Answers the Java class name the receiver is mapped to.
          
   _sstIsRmiSerializable _
          Answers true if the receiver is serializable (passed by value).
          
          
   _sstIsRmiRemotable _
          Answers true if the receiver is remotable (passed by
          reference).
          
   
   
   The above methods, along with the class mapping definitions (added to
   the application class), are used by SST to enable instances of the
   class for use with RMI. There may be some cases where you want to
   enable the class itself (versus instances of the class) for use with
   RMI. For example, you might want to have a Java client send messages
   to a Smalltalk class. If this is the case, you'll need to add the
   above methods as class methods.
   
    On AIX, SST using MQ requires threaded versions of MQ library
    
   
   
   On AIX, some SST applications that use the MQ transport layer will
   fail when using the unthreaded versions of the AIX MQ libraries. If
   you are getting the error MqCallInProgress, this may be the cause.
   
   By default, Smalltalk MQ calls will use the unthreaded libraries. To
   switch to the threaded libraries, before making your first MQ call,
   execute the call AbtMQSeriesBaseUnixSubApp threaded.
   
    Server Runtime V5.5 incompatible with ServerWorkbench V4.5 and V5.0
    
   
   
   Server Runtime V5.5 is not upward compatible with Server Runtime V4.5
   or V5.0. This means that applications packaged with Server Workbench
   V4.5 or V5.0 will not run on a Server Runtime 5.5 system. To
   workaround the problem, use one of the following options:
    1. Repackage your application using Server Workbench 5.5.
    2. Keep Server Runtime V4.5 or V5.0 installed in parallel with Server
       Runtime V5.5 on those systems that need to run applications
       packaged from both releases.
       
   
   
  Translations
  
   
   
    User-Supplied Code Page Conversion
    
   
   
   A hook has been added to the VisualAge for Smalltalk codepage
   conversion support which allows the programmer to substitute a custom
   code page conversion routine in place of the VisualAge default
   routine. This capability is particularly useful for Windows
   programmers who write programs that require translation from DBCS
   ASCII to DBCS EBCDIC because the code page conversion support for
   Windows does not support this task.
   
   Please refer to our web page located at
   http://www.software.ibm.com/ad/smalltalk/downloads/vacodepage.html
   for a Windows-only example that demonstrates usage of a custom code
   page routine.
   
  ULC
  
   
   
    ULC 3.0 supported
    
   
   
   The ULC feature of VisualAge Smalltalk Version 5.5 has changed since
   Version 5.0. VisualAge Smalltalk Version 5.0 supported ULC 1.5.
   VisualAge Smalltalk Version 5.5 supports ULC 3.0.
   
    On OS/2, ULC Client must be installed on a HPFS Driver
    
   
   
   On OS/2, the ULC Client (UIENGINE) must be installed on an HPFS driver
   due to it's use of long file names.
   
    Loading and Running the ULC Examples
    
   
   
   If you are using the Ultra Light Client Component of the Server
   Workbench Feature, you may want to load the examples that ship with
   the product. (To conserve space, these examples are not automatically
   loaded into your image.) To load these examples, select the _VA: ULC -
   Examples_ feature from the _Tools -> Load/Unload Features_ pulldown on
   the transcript window.
   
   You must have a ULC UI Engine running on your development machine to
   run these examples. Also, to run the Hierarchy Browser or Dossier ULC
   examples directly from the transcript window pulldown (_ULC ->
   Examples -> Hierarchy Browser_ or Dossier), you must first copy the
   bitmaps subdirectory in the ULCSamples directory to the image
   directory in your VisualAge Smalltalk root directory. One way to do
   this is to create a new bitmaps subdirectory in the image directory
   and copy the ULC bitmaps into this new bitmaps subdirectory.
   
    Description of ULC files that must be installed separately
    
   
   
   When you install the Server Workbench Feature, a subdirectory named
   ulc is added to your VisualAge Smalltalk V5.5 root directory. In this
   subdirectory, you will find 4 files. If you plan to use the new ULC
   component of the Server Workbench feature, you will need to install
   these 4 files using the instructions in the appropriate readme files,
   as described below. _Note:_The Windows and OS/2 UI Engine client is
   provided for both OS/2 and Windows installations since a server can
   connect to either client.
   
   
          
   _Ulcouie.exe _
          For all installations, a self extracting zip file with the OS/2
          version of the UI Engine for your OS/2 client machines and your
          OS/2 development machine.
          
   _Ulcouie.txt _
          For all installations, a readme with installation instructions
          for the above file, Ulcouie.exe
          
   _Ulcwuie.exe _
          For all installations, a self extracting installation program
          for the Windows version of the UI Engine for your Windows
          client machines and your Windows development machine.
          
   _Ulcwuie.txt _
          For all installations, a readme with installation instructions
          for the above file, Ulcwuie.exe
          
   
   
  Web Connection
  
   
   
    Debugging Web Connection applications using the interactive debugger
    
   
   
   It is not currently possible to use the interactive debugger facility
   of an XD image to debug a Web Connection application. In order to
   debug a Web Connection application (or an XML application that uses
   the Web Server Interface), perform the following steps:
    1. In the
       _AbtWebServerInterfaceBaseApp>>AbtWsiConnection>>#handleTransactio
       n:_ method, change the ExAll exception reference to ExError.
    2. In the
       _AbtWebServerInterfaceBaseApp>>Block>>#abtWsiAtEndOrWhenExceptionD
       o:_ method, replace the code with the following:
	abtWsiAtEndOrWhenExceptionDo: completionBlock
  " Code hacked to enable debugging in XD runtime image via
  the interactive debugger "

  self value.
  completionBlock value

   
       
       After making the above changes, package the application and
       execute it as usual. _Note:_Be sure to load the original code
       prior to packaging the application for production.
       
   
   
    On OS/2, starting SST-HTTP server hangs
    
   
   
   On OS/2, attempting to start a WSI Server with transport type sst-http
   causes Smalltalk to hang if TCP/IP loopback is not enabled.
   
   Eventually, a Smalltalk debugger appears with the following error
   message: Could not create socket pair: ETIMEDOUT (10060): Connection
   timed out. To correct this problem, enable loopback on OS/2 by
   performing the following steps:
    1. Open TCP/IP Configuration windows.
    2. Select loopback interface from the Interface to Configure list
       box.
    3. Select the Enable interface check box.
    4. Close the TCP/IP Configuration window.
       
   
   
   To determine if the loopback interface is working properly, type the
   following from an OS/2 command prompt:
	ping 127.0.0.1

   
   
   If loopback is properly configured, a series of messages will be
   written to the OS/2 session indicating that the target address for the
   ping was successfully contacted. Press ctrl-c to terminate the ping
   operation.
   
   After successfully configuring loopback, you should be able to use the
   sst-http interface from OS/2.
   
    Packaging an image with Web Connection image components
    
   
   
   To package your Web Connection application so that it utilizes the Web
   Connection image components, you must implement a packager method to
   force inclusion of your web parts in the packaged image.
   
   For example, implement the following method as a class method of the
   application containing your web connection parts.
	packagerIncludeClassNames

   ^self defined collect: [:i | i name ]

   
   
    #selectionType for table column gives confusing error message in properties
    
   
   
   When a Table part is dropped onto an Html Page, the _#selectionType_
   attribute for a table column contains the following selections in the
   properties table:
	<Error: No Form - Multiple Select>
	<Error: No Form - Single Select>

   
   
   These messages are a bit confusing. The _#selectionType_ attribute is
   only valid for tables that are dropped onto an Html Form part.
   
    Including the Web Server Interface Monitor in packaged applications
    
   
   
   The Web Server Interface Monitor is no longer included, by default, in
   the prerequisites for Web applications. In order to include the
   monitor in a packaged application, users should modify the
   prerequisites for web applications to include the_AbtRunHtmlPageApp_
   application. Alternatively, users can package their web applications
   using the _Tools->Browse Packaged Images_ option. You can add the
   _AbtRunHtmlPageApp_ application to the packaged image from the Package
   Control Panel without modifying application prerequisites. This
   approach is necessary for Web applications that must be loaded into an
   XD image because the _AbtRunHtmlPageApp_ application will not load
   into an XD image.
   
   For example, the sample application _AbtWebSamplesApp_ is now headless
   by default because it does not include the prerequisite
   _AbtRunHtmlPageApp_. When the packaged image for this sample is
   started, no windows will open. The application _AbtWebSamplesApp_ can
   be loaded into a passive XD image and packaged if desired.
   
   The application _AbtWebSamplesWithMonitorUIApp_ contains prerequisites
   to include the Web Server Interface Monitor as well as all the sample
   parts from _AbtWebSamplesApp_. This application cannot be loaded into
   an XD passive image. _Note:_Applications constructed before v4.5
   already include the prerequisite _AbtRunHtmlPageApp_, so no special
   action is necessary.
   
  XML
  
   
   
    XML - SgmlException when IDREF specified before ID definition
    
   
   
   Validation routine signals an exception when an XML attribute of type
   IDREF/IDREFS contains a value that has not yet been defined by an ID
   field. This problem occurs when the ID is defined later in the
   document. Validation of IDREF and IDREFS fields should be performed
   after all elements have been processed.
   
   In the example below, M.Pogue has subordinate 'A.Bagchi', but
   'A.Bagchi' is defined AFTER 'M.Pogue'. This currently causes a
   validation error because subordinates is an IDREFS field.

 <personnel>
  <person id="M.Pogue" >
    <name><family>Pogue</family> <given>Mike</given></name>
    <email>mpogue@us.ibm.com</email>
    <link subordinates=" A.Bagchi"/>
  </person>

  <person id="A.Bagchi">
    <name><family>Bagchi</family> <given>Anupam</given></name>
    <email>abagchi@us.ibm.com</email>
    <link manager=    "M.Pogue"/>
  </person>
 </personnel></xmp>

   
   
   To correct this problem, modify the method __SgmlIdRefData
   class>>#abtValidateAttributeValue:forHandler:, so that it always
   returns 'true'. Any IDREF fields that remain unresolved will be
   reported via an exception when parsing is completed.
	abtValidateAttributeValue: aValue forHandler: anAbtSaxHandler
        " Make sure that passed id value exists in this document  "

        ( anAbtSaxHandler document idTable  includesKey: aValue )
                ifFalse: [ anAbtSaxHandler unresolvedIdRefs add: aValue ].

        " Always answer true.  Unresolved references will be reported after parsing completes "
        ^true

   
   
    Walkback during XML output serialization
    
   
   
   Walkback occurs during XML output serialization due to unimplemented
   method _#printAttribute:value:toStream:_ To correct this problem,
   change the method
   _AbtXmlOutputSerializer>>#printAttributesFor:on:mapping:_ as follows.
   
   Change the following code:
  self printAttribute: attrMap attribute
        value:  (anObject abtAtAttribute: attrMap classAttribute asSymbol)
        toStream: aStream ]]

   
   
   to the following code:
  self printAttribute: attrMap attribute
        value:  (anObject abtAtAttribute: attrMap classAttribute asSymbol)
        on: aStream ]]

   
   
    Using the XML server examples
    
   
   
   To try out the XML server samples, perform the following steps:
   
   
          
   _Testing XML request handlers over HTTP _
          
         1. From the VisualAge Organizer, select the
            _AbtXmlServerSamplesUIApp_ application.
         2. Select the _AbtXmlSampleHttpClientTesterView_ part.
         3. Enter an XML string or a piece of code that evaluates to an
            XML string
	AbtXmlSampleCustomerRequest xmlTestString1
	AbtXmlSampleCustomerRequest xmlTestString2
         4. From the Actions menu, select the Open WSI monitor option to
            bring up the Web Server Interface monitor. Follow the
            instructions in the Web Connection User's Guide to start a
            WSI server with transport type wsi-tcp
         5. Specifiy the URL that will handle the request:
 	http://myserver/cgi-bin/abtwsac.exe/AbtXmlSampleCustomerRequestHandler
         6. Enable the Options->Inspect result option so that you can
            view the returned XML response string
         7. Select the code string in the text box, and select the
            Actions->Evaluate and send menu option (or use pop-up menu
            for text box).
            
   
          
          After the command is processed, an inspector should open to
          display an XML string that contains the results.
          
   _Testing XML request handlers over sockets (very similar to the steps
          for testing over HTTP) _
          
         1. From the VisualAge Organizer, select the
            _AbtXmlServerSamplesUIApp_ application.
         2. Select the _AbtXmlSampleSocketClientTesterView_ part.
         3. Enter an XML string or a piece of code that evaluates to an
            XML string
	AbtXmlSampleCustomerRequest xmlTestString1
	AbtXmlSampleCustomerRequest xmlTestString2
         4. From the Actions menu, select the Open WSI monitor option to
            bring up the Web Server Interface monitor. Start a WSI server
            with transport type xml-tcp and select the request handler
            class that you wish to use for handling incoming requests on
            the socket. For example:
 	AbtXmlSampleCustomerSaxRequestWsiHandler
         5. From the XML socket client tester view, specify the server
            and port number for the request that is to be made (the same
            server and port from step #4 above).
         6. Enable the Options->Inspect result option so that you can
            view the returned XML response string.
         7. Select the code string in the text box, and select the
            Actions->Evaluate and send menu option (or use pop-up menu
            for text box).
            
   
          
          After the command is processed, an inspector should open to
          display an XML string that contains the results.
          
   
   
    On Unix, testing the XML server sample AbtXmlSampleCustomerRequestHandler
    
   
   
   The XML server sample named _AbtXmlSampleCustomerRequestHandler_
   contains code with hard coded directory references that do not resolve
   properly. If you would like to test this sample, you must first do the
   following:
    1. Create a subdirectory named xml from your VisualAge base client
       directory. For example:
 	mkdir xml
    2. Copy the xml files from the directory /opt/IBMvast/5.5/xml to the
       newly created xml directory. For example:
	cd <vast client directory> /xml
	cp /opt/IBMvast/5.5/xml/*.* .

   
   
    Packaged image with XML image components
    
   
   
   If you wish to package your XML application so that it utilizes the
   XML image components, you must implement a packager method to force
   inclusion of your XML request handler parts in the packaged image. For
   example, you can implement the following method as a class method of
   the application containing your XML request handler parts:
  packagerIncludeClassNames 
  | handlers |
    handlers := AbtXmlServerSamplesApp defined select: [:aClass |
     aClass inheritsFrom: AbtXmlWsiHandler ].
    ^handlers collect: [:aClass | aClass name ]

   
   
   For reduced runtime images that are packaged without the XML image
   components, all XML request handlers are automatically included in the
   packaged image. _Note:_The Web Connection feature must be loaded in
   order to package an XML application that utilizes the WSI
   communications features.
   
    Packaging considerations when using XML input serialization
    
   
   
   If the input serialization functionality of the XML feature is used to
   map incoming XML requests into Smalltalk business objects, the
   packager will exclude classes that are not specifically referenced in
   code. The specific sequence of events that may cause packaging
   concerns is as follows:
    1. Parse an XML file to construct a DOM (document object model).
    2. Send the _#mapUsing:_ method to the DOM and pass it a valid
       instance of the _AbtXmlMappingSpec_ class.
       
   
   
   The _#mapUsing:_ API uses the passed mapping specification to build an
   object from the contents of the DOM. However, the steps above do not
   cause any actual references to the class name of the constructed
   instance. Therefore, packaging rules must be used to instruct the
   packager that unreferenced classes should be included in the packaged
   image.
   
   For example, the _#packagerIncludeClassNames_ packager method (a class
   method) can be implemented in the application class. For example, if
   _MyModel1_ and _MyModel2_' are classes in _MyApplication_, then the
   method below should be implemented as a class method in
   _MyApplication_.
	packagerIncludeClassNames
   " Include class names that might be constructed via XML mapping "

   ^#(MyModel1 MyModel2)

   
   
    XML code page conversion has unsupported encodings
    
   
   
   The XML parser automatically performs code page conversion before
   attempting to parse an XML stream. Many code pages are handled
   seamlessly using the default code page conversion routine of the
   runtime operating system. However, there are some character encodings
   that cannot be converted. Unsupported code page conversions cause
   walkbacks at execution time.
   
   The following code pages are not supported:
     * EUC_JP conversion is not properly supported by native Windows code
       page routines. A Windows implementation of ICONV supports EUC_JP.
       To download ICONV, see
       http://www.ibm.com/software/ad/smalltalk/downloads/vacodepage.htm
       l Using the ICONV support, additional code pages, including
       EUC_JP, can be supported.
     * The code page ISO-2022-JP is not supported by native routines or
       by ICONV.
       
   
   
   The VisualAge XML support attempts to map XML character set encodings
   to valid code pages. The default mappings can be overridden using the
   API shown in the following example:
	AbtXmlStreamConverter mapEncoding: 'UTF-8' toCodePage:  65001.

   
   
   VisualAge uses the code page conversion support APIs that are built in
   to each of the supported platforms. Therefore, code page mappings may
   be different for different operating systems. If you encounter a
   debugger with the following message it is likely that you have
   encountered an unmapped or mismapped encoding.
	Abt.Nls.160.e: Conversion from code page <sourceCodePage> to code page <targetCodePage> is not supported.

   
     _________________________________________________________________
   
                                 DISCLAIMER
                                       
   
   
   THIS DOCUMENT IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IBM
   DISCLAIMS ALL WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING
   WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR
   PURPOSE AND MERCHANTABILITY WITH RESPECT TO THE INFORMATION IN THIS
   DOCUMENT. BY FURNISHING THIS DOCUMENT, IBM GRANTS NO LICENSES TO ANY
   PATENTS OR COPYRIGHTS.
   
   (C) Copyright IBM Corporation 2000. All rights reserved. 
