IBM VisualAge Smalltalk Readme

Note:

*On OS/2, the Version 5.5.2 files must be unzipped to an HPFS drive because the Version 5.5.2 files contain long file names. If the files are unzipped to a FAT drive, the unzip program will not give you any error messages. However, 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.2 for development environments: the library manager and the client. You must install both the Version 5.5.2 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.

Note:

If you have previously installed VisualAge Smalltalk Enterprise Version 5.5.1, the directories icsrn551, icspk551, and image551 will not be overwritten. However, the contents of other directories may be overwritten. You should backup any files you may need from the other directories.

You can install the Version 5.5.2 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 first and then the library manager.

To obtain Version 5.5.2, follow these steps:

1. Download the appropriate files from the VisualAge Smalltalk service ftp site to a temporary directory.

   Note:

   On OS/2, the Version 5.5.2 files must be unzipped to an HPFS drive because the Version 5.5.2 files contain long file names. If the files are unzipped to a FAT driver, the unzip program will not give you any error messages. However, 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.2 files using whatever option your unzip program provides to restore the subdirectory structure of the Version 5.5.2 file. Be sure that your unzip program restores the files with the same case that they were zipped with in the Version 5.5.2 file, or use whatever option your unzip program provides to restore the case of the zipped Version 5.5.2 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 va552_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 va552_cw.zip
     

   • Untar

     tar -xvf va552_ml.tar
     

Before installing Version 5.5.2, follow these steps:

1. If EMSRV is running from the directory to be updated, stop EMSRV prior to installing Version 5.5.2.
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.2 zipped file, do the following:

1. Change your current working directory to the manager or client subdirectory of the temporary directory:
   • cd_m
   • cd_c
2. Change directories:

   cd install_w
   

3. Run setup

To install Server Runtime, do the following:

1. Create a directory into which you will install VisualAge Smalltalk 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 va552_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.2 zipped file, do the following:

1. Change your current working directory to the manager or client subdirectory of the temporary directory:
   • cd_m
   • cd_c
2. Change directories:

   cd install_o
   

3. Run install

To install Server Runtime, do the following:

1. Create a directory into which you will install VisualAge Smalltalk 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 va552_so.zip
   

Unix

Note:

On the Sun and HP platforms, create the /opt/IBMvast/5.5 directory before starting to install.

Note:

You must have root authority to install on Unix.

To install on Unix, from the temporary directory where you downloaded and extracted the files from the Version 5.5.2 zipped file, do the following:

1. Change your current working directory to the manager or client subdirectory of the temporary directory:
   • cd_m
   • cd_c
2. Change your current working directory to a platform-appropriate subdirectory:
   • install_a for AIX
   • install_h for HP-UX
   • 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. After selecting a new feature to install, sometimes the Next button is not enabled due to an error in synchronization of the features. To correct this problem, select the Back button and then on the License Agreement screen, select the Accept 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 va552_sa.taz va552_sa.tar.Z;zcat va552_sa.tar.Z|tar -xvf -

Sun

Decompress and untar as follows:

mv va552_ss.taz va552_ss.tar.Z;zcat va552_ss.tar.Z|tar -xvf -

Linux

To install a manager on Linux:

1. You should have already downloaded the Linux manager code va552_ml.taz to a temporary directory.
2. Move the Linux manager code into the /opt subdirectory tree and then execute:

   mv va552_ml.taz va552_ml.tar.Z;zcat va552_ml.tar.Z|tar -Pxvf  -
   

3. Perform 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. You may need to first create this subdirectory on your machine.

NetWare

To install a manager on NetWare:

1. You should have already installed the executables by downloading the NetWare manager code, va552_mn.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

After installing VisualAge Smalltalk Version 5.5.2

The Version 5.5.2 installation automatically merges the Version 5.5.2 code into the Version 5.5 or 5.5.1 manager.

If you had previously installed Version 5.5 or 5.5.1, before you use VisualAge Smalltalk Version 5.5.2, 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 complete the install, you can then load your versioned work from the new Version 5.5.2 manager into the VisualAge Smalltalk Version 5.5.2 client.

Unlocking products

Note:

Any features that were unlocked in the VisualAge Smalltalk Enterprise Version 5.5 or 5.5.1 image must be unlocked in the VisualAge Smalltalk Enterprise Version 5.5.2 image. Ensure that the unlock tool is pointing to the new VisualAge Smalltalk Enterprise Version 5.5.2 ini file in the image552 directory.

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

ULC 3.1

The ULC feature of VisualAge Smalltalk Version 5.5.2 has changed since Version 5.5.1. VisualAge Smalltalk Version 5.5 and 5.5.1 support ULC 3.0. VisualAge Smalltalk Version 5.5.2 supports ULC 3.1. See the VisualAge Smalltalk Ultra Light Client Guide and Reference for detailed information on ULC 3.1 changes.

IBM Smalltalk Image Provided

You are no longer required to build your own IBM Smalltalk Image. Version 5.5.2 provides a prebuilt IBM Smalltalk image:

Windows and OS/2

On Windows and OS/2, the image is <vast>\newimage\ibmst.icx

UNIX

On UNIX, the image is /opt/IBMvast/5.5/newimage/ibmst.icx

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

The RMI in Server Smalltalk will run under JDK 1.3, using the same techniques that were required for JDK 1.2.

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 .
• 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.2
  • VisualAge Smalltalk Installation Guide
  • VisualAge Smalltalk Ultra Light Client Guide and Reference
  • VisualAge Smalltalk Server Smalltalk Guide
  • VisualAge Smalltalk User's Guide
  • IBM Smalltalk User's Guide
  • IBM Smalltalk Programmer's Reference
• The following documents had changes made for Version 5.5.1
  • VisualAge Smalltalk Installation Guide
  • VisualAge Smalltalk Parts Reference
  • VisualAge Smalltalk Server Guide
  • VisualAge Smalltalk Server Smalltalk Guide
  • VisualAge Smalltalk User's Guide
  • VisualAge Smalltalk Web Connection User's Guide
  • VisualAge Smalltalk Ultra Light Client Guide and Reference
  • IBM Smalltalk Programmer's Reference
  • IBM Smalltalk User's Guide

Component fixes from Version 5.5.1

This section documents the fixes that were in Version 5.5.1. These fixes are included in Version 5.5.2. These are fixes to problems reported to IBM by customers (APARs) and problems reported through other sources.

APARs

Fixes are included for the following problems found by customers. The problems are listed by APAR number.

Problems found by other sources

Fixes are included for the following problems found by IBM. The problems are listed by defect number.

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

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 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 for 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.

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, 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

SST Server Process refactored

In versions prior to 5.5.2, the server process handled its first step--pulling incoming requests off of the wire--serially. The code that received the incoming messages executed on the server process. For Version 5.5.2, we have given SST programmers the ability to use a dispatcher to handle how the incoming message reception code gets executed, giving you the chance to use processes other than the server process. In many applications, this will help performance and throughput, especially if your SST application involves large requests made from the client to the server and heavy loads.

In some rare circumstances, this change could also help with stability. Consider what would happen if a client to your SST server application sends only 100 bytes out of a 200 byte request. This situation might arise due to a hiccup in your network (this kind of hiccup is actually very rare), or perhaps due to a malicious client. For this example, let's say you are using TCP/IP for your transport. You will issue a socket receive() call, expecting 200 bytes. This call will block until those 200 bytes are received; in this case, it blocks forever. If this receive() call is made on your server process, that process is blocked indefinitely, and your server will stop responding to incoming requests.

With the changes made in Version 5.5.2, the reception of incoming requests does not have to be executed on the server process. The invocation handler now holds onto a second dispatcher, and the work of pulling the incoming requests off of the wire is managed by this dispatcher. If you were to use, for example, an SstPooledDispatcher here, the requests would happen on processes managed by that dispatcher, and your server will stay up if it receives one of these partial messages. You could even write your own dispatcher that would timeout any call not fully received after n seconds.

In Version 5.5.2, there are two new options in the SstInvocationConfiguration for this new function:

marshalWorkerManager

Set this to an instance of SstWorkerManager. This worker manager will manage the processes that perform the receives (named the marshaling processes). If you set this to nil, SST will act as it did in versions prior to 5.5.2; i.e., the receive will occur on the server process.

marshalWorkerPriority

Set this to an integer. This will determine the priority of the marshaling processes.

HelloWorld haltHelloWorld

System image startUpClass walkbackFileName: 'runtimeWB.log'.  HelloWorld haltHelloWorld

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.1 supported

The ULC feature of VisualAge Smalltalk Version 5.5.2 has changed since Version 5.5 and 5.5.1. VisualAge Smalltalk Version 5.0 supported ULC 1.5. VisualAge Smalltalk Version 5.5 and 5.5.1 supported ULC 3.0. VisualAge Smalltalk Version 5.5.2 supports ULC 3.1.

On OS/2 Running ULC Samples

On OS/2, after you install the UIEngine (by running the command UlcOUiE.exe /dir), you must change each command file (.cmd) in the ulc/uiengine/bin directory that has a name that begins with runClient. Edit the .cmd file and change the run.bat call to the run.cmd call.

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 Version 5.5.2 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.

Uninstall

Client uninstall fix for Windows 95, Windows 98, and Windows ME

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 theAbtRunHtmlPageApp 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

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.html 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.