IBM VisualAge Smalltalk Readme


Contents

Welcome to VisualAge Version 6.0.1


Welcome to VisualAge Version 6.0.1

.

Late-breaking news, technical tips, and product updates

Please refer to the VisualAge Smalltalk web page 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 link to the ftp site for product updates from the Support section. You can get to the VisualAge Smalltalk web pages by going to the IBM web page and searching for "VisualAge Smalltalk" in document titles.

You can download the latest product updates from the VisualAge Smalltalk service ftp site.

Version 6.0.1 files and installation

Installing VisualAge Smalltalk

For installation information, see cd_m\doc\instgd.htm or cd_c\doc\instgd.htm in the CD drive or the temporary directory where you extracted the manager or client installation files. To install VisualAge Smalltalk, follow the instructions for your specific platform.

. Before installing Version 6.0.1, follow these steps:

  1. If EMSRV is running from the directory to be updated, stop EMSRV.
  2. Stop any running VisualAge Smalltalk images.

VisualAge Smalltalk Migration Guide

If you have a version prior to VisualAge Smalltalk Version 6.0.1 installed, please refer to the Migration Guide for important information before using VisualAge Smalltalk Version 6.0.1. The Migration Guide can be installed with the VisualAge Smalltalk Client by selecting the "VisualAge Smalltalk Documentation" feature. It is also available in PDF format on the VisualAge Smalltalk web page.

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.

APARs

Product Enhancements in VAST V6.0

VisualAge Smalltalk lets programmers create and deploy e-business applications that are cross-platform, object-oriented, and integrated with IBM's key initiatives:

Product Enhancements in VAST V6.0.1

APARs fixed in Version 6.0

PQ45824 ABRREMOVEINTERESTFROM: DOES NOT WORK FOR PROMOTED FEATURES
PQ46370 SCI Sockets cannot send buffers greater then 8MB
PQ47705 ZERO SUPPRESSED CONVERTER SETTING DOES NOT WORK FOR CONTAINER
PQ48173 CONTAINER COLUMN WITH STRING CONVERTER, EMPTYMAKESDEFAULT=TRUE
PQ48934 EWLIST>> ITEMS: DOES NOT ACCOUNT FOR ENDEDIT WHEN EDITING IS IN
PQ49049 JAPANESE IME - CONTROL+H FOLLOWED BY DELETE IN VAST MLE RESULTS
PQ49602 WALKBACK RECEIVED WHEN FEATURE NAME INCLUDES ( OR )
PQ49632 NUMERIC FORMATTED TEXT INCORRECTLY INSERTS/OVERLAYS
PQ49800 AFTER LOADING OLD SETTINGS VIEW CONFIGURATION MAP, CAN NOT OPEN
PQ49837 SciSend/SciRecv hangs server on socket primitive
PQ49842 Explicit futures leak when #invoke:at: is curtailed by timeout
PQ50299 WALKBACK WHEN USER-DEFINED TABBING IN CONTAINER DETAILS AFTER
PQ50425 WALKBACK FROM RECALCULATEPARTBUILDERRECORDFROMARCHIVALCODE
PQ50837 RMI ConnectionManager walkback with nil connection handle
PQ51720 WALKBACK WHEN ATTEMPTING TO OPEN WINDOW A SECOND TIME.
PQ52491 MLE FIELD ALLOWS MORE THAN MAX CHARACTERS DEFINED BY USER.
PQ52848 NUMERIC CONVERTER INDICATES A FIELD CHANGE FOR A NIL VALUE
PQ53006 Unable to resolve remote space location at server
PQ54905 whenTimeoutInSeconds method returns prematurely
PQ55555 Incomplete support for DBCS languages
PQ56040 IN V5.5 WIDGETS CAN NOT MANIPULATE THE IME USING METHODS LIKE
14032 Web Connection Running out of sockets on Windows

APARs fixed in Version 6.0.1

PQ08131 ORGANIZER->TOOLS->FIND OK DEFAULT DOES NOT WORK
PQ48172 REDRAW PROBLEM WHEN THE WINDOW INCLUDES RADIO BUTTONS AND ALLOWSHELLRESIZE=TRUE
PQ58658 ARCHIVAL CODE SHOULD OPTIONALLY INCLUDE VALUES FROM EXTRAINFO INSTANCE VARIABLE
PQ58963 STOP SELECTOR NOT GIVEN CONTROL IF NT SERVICE IS ACTIVE WHEN SHUTDOWN OCCURS
PQ61395 SSTERROR DOES NOT UNDERSTAND #ADDRESS
PQ61495 WALKBACK INDICATING UNDEFINEDOBJECT (NIL) DNU TERMINATE
PQ62131 NODIALOG GOES INTO A WAIT AFTER INITIALIZEBREAKHANDLER FAILS
PQ62227 UNABLE TO SAVE CLASS VARIABLE VALUES WHEN PACKAGING IC
PQ62316 HASH VALUE FOR EQUIVALENT SCALED DECIMAL NUMBERS ARE NOT THE SAME
PQ63542 PACKAGING AS ICS WITH LARGE NUMBER OF SYMBOLS CAUSES PERFORMANCE
PQ66012 XML TEXT ELEMENT WRITING EXTRA SPACES

Additional fixes in Version 6.0.1

14979 - CfsDirectoryDescriptor>>#directoryEntry: need stAtime & stCtime
14920 - Walkback streaming over an OrderedCollection using #next:
14945 - Time format specifier %r is wrongly defined
14968 - literal == literal sometimes gives wrong answer
14927 - EsString>>#bindWithArguments: verification too rigid
14887 - FD_SETSIZE is too severely constrained on WinSock platforms
14683 - TcpLightTransport officialHostNameFor: may return unqualified
14695 - SstHttpSession>>#isNew method returns false when sent to the
14702 - SstHttpUrl>#fetch: should ensure shutDown
14718 - InvocationHandler drops error on new connection
14825 - SstServerApplicationContext state access is not thread safe
14833 - SstHttpUrl>>fetch should provide for a proxy exception list.
14835 - Add support Sst HTTP proxy
14842 - With the addition of SSL support, you should be able to do the
14851 - Servlet Engine fails to give notification on failed startup
14852 - SstPool needs #remove:
14853 - SstPool next should allow for create failure.
14855 - MVS polling socket demultiplexer prevents low priority processe
14857 - Provide transport using UNIX domain sockets
14881 - client closing socket connection is not accounted for
14883 - handleIncomingConnection does not catch error on Connection
14888 - tcp transport fails to honor socket FD_SETSIZE constraints
14902 - SCI Errors on Server Process on dirty startUp
14906 - ServletEngine fails to indicate failed startUp
14938 - mime-type mappings are missing for XML
14980 - findReadyConnection answers wrong SstError if isShutDown
14982 - TcpLightTransport DNU #returnAddress
14924 - Support for MQCONNX and MQBEGIN options
12350 - Support for v5.x MQINQ attributes
14937 - Ensure that default configuration is correct for user's setup
14859 - SciLocalSockets should support socket options
14858 - Local sockets addrs must implement =
14886 - SciSocketConstants::FDSETSIZE not initialized properly
14898 - SciSocket>>close should protect against closing if closed
14887 - FD_SETSIZE is too severely constrained on WinSock platforms
14973 - Error Code incorrectly set to #EBADF instead of constant value
14948 - SSL interface should support certificate chain files
14669 - SstSoapFault>>#raise should signal proper exception
14731 - Serialization of XML schema definitions
14826 - Admin. sample does not always select correct container in a development image where the service is deployed to multiple containers.
14837 - SstWSEncodingStrategy #register:as: is reversed.
14841 - SstWSHttpDispatchHandler should use port manager
14846 - #formattingEnabled switch is not always respected
14865 - Bogus Web Services files in nls subdirectory
14879 - Add 'CreationMethod' to ClassElementMapping of XML mapping spec
14723 - Service exposed on wrong endpoint
14799 - Support for HTTPS (client)
14747 - Port manager does not support multiple URL endpoints
14748 - URL based service resolution in support of doc/lit services
14862 - Add creationMethod for handler creation
14875 - Web services should respect SST forwardExceptions
14759 - Packager warnings due to unimplemented methods
14813 - Fault message construction not consistent
14828 - Issue more informative message on attribute value error
14835 - HTTP proxy support
14836 - Class element mapping not resolved when serializing from schema
14840 - Stack overflow during XML serialization with unprefixed elements
14843 - AbtXmlMappedAttribute>>#abrAsString returns nil when object is set
14844 - AbtXmlMappedElement default set logic should allow any object
14854 - Serialization of AbtXmlMappedElement when type has
14856 - Need mapping for schema import (missing classes AbtXmlSchemaImport and AbtXmlSchemaInclude)
14876 - Minor Database refactoring
14890 - Improper resolution of WSDL extension
14891 - Signal exception when returned message is not SOAP
14895 - Container needs API to create without registering
14897 - Add #isRequired method to AbtXmlSchemaAttribute
14900 - AbtXmlMappedElements do not handle setting collections
14904 - Remote client cannot access local endpoints
14909 - Unrecognized WSDL extensions are not added to WSDL model
14910 - xsi:type not specified for complex types
14912 - Support for xsi:nil and nillable attribute
14918 - HTTP 'hostname' required by some MS servers
14923 - XML HTTP reader has redundant carriage return in HTTP header
14928 - Proper mapping for restricted types
14930 - Empty 'xsd:string' elements should convert to an empty string
14931 - XML validation error not flagged by DOM parser
14932 - Server does not return a result string if exception occurs during serialization
14933 - XML attribute namespaces not correctly determined
14934 - Enable lazy-initialization of handlers
14935 - Allow for one-argument GetSelector to enable LookupTable mapping
14936 - Runtime error using minLength facet
14940 - Automatic mapping when schema type matches class name
14941 - sSLString* mentods broken for Oracle 8 14942 - XML extension types are not rendered properly
14943 - Nested SOAP arrays do not serialize properly
14944 - Improper/incomplete mapping for SOAP multi-reference elements
14946 - Simplify XML resource readers
14947 - Sets not properly wrapped as SstSoapArray instances
14950 - Modify schema type resolution.
14951 - Suppress serialization of nil attribute values when an attribute mapping has its 'Required' attribute set to false.
14952 - Release updated WSDL 1.1 schema (sstwsdl.xsd).
14957 - XML schema serialization bug.
14958 - WSDL part cannot resolve typeObject when locally qualified
14959 - Enable wildcard and mixed mappings for DOM
14960 - Enable relative resource qualification for schema include handler
14961 - Enable mapping for simpleContent in AbtXmlMappedElement
14963 - SstSoapArray contents should be initialized
14965 - Parser errantly removes carriage return in text field containing entity references
14969 - Empty string processing by mapping parser
14974 - Invalid namespace namespace context during parsing
14981 - XML schema facet values need conversion
14983 - XML - minOccurs for AbtXmlSchemaElement should be 1

Application Builder

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.

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 VA Smalltalk with the ksh command:
export LANG=en_US

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

The output should look like:
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 UNIX, "X Error: BadWindow" message appears for Slider part

Each time the Slider part is repainted the "X Error: BadWindow (invalid Window parameter)" message is printed in the xterm window which VisualAge Smalltalk was launched.

The Slider part still functions normally.

Base

Modify validation of EsString>>#bindWithArguments:

As a result of the changes made by the fix to defect 19427 in the EsString>>#bindWithArguments: processing (which also affects all EsString>>#bindWith:..... methods), documentation for the handling of missing or extra arguments is modified, and documentaiton for the pre-existing handling of the %0 sequence in the template string is added. These changes will be reflected in the IBM Smalltalk Programmers Reference when it is republished.
Update IBM Smalltalk Programmers Reference, Chapter 13: NLS, section "Tools for developing International software", sub-section "Using message templates":
1) In the paragraph beginning "A template string is expanded...", delete the last sentence.
2) Add a new paragraph following this paragraph:
There are also 2 special escape sequences. The double percent escape sequence ('%%') is replaced by a single percent chatacter in the composite message. The percent zero escape sequence ('%0') is replace by a platform line delimiter in the composite message.
3) in the paragraph beginning with "A template string permits ...", replace the last sentence with:
Argument that are not referenced in the template string are ignored. Template string references to missing arguments are replaced by the escape sequence itself.
4) Repace the last entry in the "Resultant message" column of Table 49 with the following:
'Missing arguments are %2.'

ScaledDecimal>>#hash corrected

The fix for APAR PQ62316 changed the algorithm used to hash a ScaledDecimal object. This change affects existing collections that rely on the hash value. The affected collections are, at least, KeyedCollection (and its subclasses) and Set (and its subclasses).

If your application uses ScaledDecimal objects as keys for any of these hashed collections, you MUST recompute the hash values after loading the fix and before modifying the collection in any way. To recompute the hash values, send the rehash message to the collection (for example, myDictionaryKeyedWithScaledDecimals rehash).

On OS/2, Cannot start VisualAge Smalltalk V6.0.* if previous version is running

On OS/2, if you have an older version of VisualAge Smalltalk running, when you attempt to start VisualAge Smalltalk 6.0.*, you will fail with the following message:

"The program in session encountered a problem. Registry: the system could not demand load the application's segment ABT->ESVM40. EsReportWarning is in error. Help Sys127."

To workaround this problem, start VA Smalltalk 6.0.* before starting the older version. Another solution is to replace the bin directory of your older version with a copy of the bin directory that is installed with VisualAge Smalltalk 6.0.*.

On UNIX, cannot read stack dump files generated on a different platform

When your development image is running on UNIX, you will not be able to read stack dump files that were generated on an architecture with different endian-ness. Doing so will cause a walkback.

To work around this problem, swipe and execute the following doit from your development environment:

PlatformLibrary mapLogicalName: 'EsLoadAndSave' toPhysicalName: 'libeslsi40'

On Linux, Ghost dialog windows may appear

Under certain Linux configurations, some operations that use progress dialogs can cause empty or "phantom" dialog boxes to remain after the operation has completed. These phantom dialog boxes can show up as a small rectange that is completely blank and cannot be moved.

To work around this problem, make the following modification to EtWindow>>#execLongOperation:message:allowCancel:showProgress:
...
aBlock argumentCount = 1
ifTrue: [runBlock := [aBlock value: inProgressDialog]]
ifFalse: [runBlock := [(Delay forMilliseconds: 100) wait. aBlock value]].
...

Add-on products fail to load because they define Object>>#->

The Object>>#-> method has been added as a convenience for constructing instances of Associations (for example, evaluating the expression 'upperLeft' -> (0@0) will answer anAssociation with 'upperLeft' as the key and 0@0 as the value). Some add-on products have extended Object with this same method. One such product is the RefactoringBrowser. Attempting to load such a product will cause a conflict and result in a load failure with a message similar to the following:
Error: 330 Cannot complete the load because Object>>#-> is defined by RBParserVAApp and CLDT
NOTE: The method collisions will be resolved if you reload after executing:
EmImageBuilder cancelIfMethodsCollide: false

Following the suggested course of action will allow the add-on product to load correctly.

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 is not complete in this release are categorized as ANSI-Unimplemented.

The following restrictions with respect to ANSI Smalltalk are in force for this release:
The following Exception methods are not functional
isNested
outer
pass
resignalAs:
retry
retryUsing:

The following DateAndTime methods are not functional:
timeZoneAbbreviation
timeZoneName

The MessageNotUnderstood exception class is provided, but is not signaled by the standard #doesNotUnderstand: method.

The ZeroDivide exception class is provided, but is not signaled when a divide by zero occurs.

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

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

On any OS/2 command line enter ping localhost. This command should return some data 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:
  1. From an OS/2 command line, enter hostname
  2. 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)
  1. Set up Netscape 4 (Navigator) as follows:
  2. Select Edit... Preferences...
  3. Double-click Advanced in the Category tree.
  4. Click Proxies in the Advanced subtree.
  5. Click View at the Manual Proxy Configuration selection.
  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 comma.
  7. 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

  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.

Communications

Local Socket Enhancements

Support for socket options get/set via the setsockopt and getsockopt function calls, previously available only for TCP stream and datagram sockets, has been added for Local Sockets on Linux/Unix platforms in V 6.0.1. There are two basic types of options: boolean options that enable/disable specific flags and others that set/get configurable features. Here are the names of the options that are typically supported by
the underlying TCP/IP stack: SODEBUG, SOACCEPTCONN, SOTYPE, SOLINGER, SOREUSEADDR, SOKEEPALIVE, SOSNDBUF, SODONTROUTE, SOBROADCAST, SOERROR, SODONTLINGER, SORCVBUF. The operations use a boolean for the following options:
SOACCEPTCONN, SODEBUG, SOREUSEADDR, SODONTROUTE, SOKEEPALIVE, SOBROADCAST, SODONTLINGER.
The operations use an integer for the following options. SOERROR, SOSNDBUF, SOTYPE, SORCVBUF.
The operations use a two entry array for the SOLINGER option. The first entry is a boolean and the second is an integer.

In addition, a pair of connected local sockets can now be created via the SciSocketManager>>socketpair: call. For example, to create a pair of connected local stream sockets, call SciSocketManager default socketpair: SciSocketConstants::SOCKSTREAM. A collection containing a pair of connected local stream sockets will be returned ready for use.

On Solaris, incorrect version of libsslthread.so in Server Runtime Package

A backlevel version of libsslthread.so was included in the Server Runtime zips for Solaris. To deploy SSL on Solaris, copy the libsslthread.so file that resides in the /opt/IBMvast/6.0/bin directory of your development environment into the /opt/IBMvast/6.0/serverbin directory for your server runtime application. This file supports multi-threaded SSL applications.

Local Socket message size limitations.

By default, the send and receive buffers used for local sockets are set at 32 K (32768 bytes). In addition, there are platform-dependent limitations the programmer should be aware of. On Linux, the size of messages sent over a local socket should not exceed 63 KB, (64,512 bytes). On Solaris, the message size should not exceed 64 KB (65536 bytes). On HP-UX, the message size should not exceed 32 KB (32768 bytes). Finally, at the time of this writing, the limits on AIX are 2 KB (2048 bytes) for local datagram sockets and 4 KB (4096 bytes) for local stream sockets.

On Solaris, HP-UX and Linux, APPC and CPIC not supported

VisualAge Smalltalk Enterprise V6.0.* does not support APPC and CPIC on Solaris, HP-UX or Linux.

On Linux and HP-UX, MQ now supported

Support has been added for MQSeries on Linux and HP-UX platforms.

SSL support

The Secure Socket Layer (SSL) support for VisualAge Smalltalk 6.0.* uses OpenSSL binaries. OpenSSL an open source implementation of SSL/TLS based on the SSLeay library developed by Eric A. Young and Tim J. Hudson. The use of OpenSSL is provided under a dual license, the OpenSSL license and the SSLeay license. A copy of this license can be found the Programmer's Reference. SSL is not supported on MVS and OS/2 platforms.

MQSeries on MVS

When loading the MQSeries feature on MVS, users will notice the following warning...

Warning: 91 Defined global MQConnectX in unmanaged namespace while loading AbtMQCall class>>connectXTo:with:.

This error is due to the existence of the MQConnectX function in the AbtMQSeriesBaseApp while not being defined as it should in the AbtMQSeriesMVSSubApp. Although this problem will not break applications created with versions of VisualAge Smalltalk up to and including V6.0, this function will not be available to new applications unless defined. To avoid this error message a definition for the function can be placed in AbtMQSeriesMVSSubApp class>> _PRAGMA_AbtMQSeriesFunctionsMVS by adding the following code to the pragma declaration...

    (name: MQConnectX isConstant: true valueExpression:
        '(PlatformFunction callingConvention: #c
            function: 'MQCONNX'
            library: nil
            parameterTypes: #(#pointer #pointer #pointer #pointer #pointer)
            returnType: #void)')

Database

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.

1. Logon to SQL*PLUS
sqlplus scott/tiger
2. Execute the file
SQL> @vast\samples\oracle\sample.sql

ODBC Drivers are no longer shipped with VisualAge Smalltalk

ODBC drivers have not been shipped with VisualAge Smalltalk since Version 4.5. 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 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

DBCS

DBCS Notes on installing VisualAge Smalltalk

When installing on a DBCS machine please remember the following:

1.If you are using OS/2 Warp 4.0J, you must apply Warp J4 Fixpack FX00004 before using VisualAge Smalltalk.
2.If you are using a DBCS version of OS/2 Warp 4.0, other than OS/2 Warp 4.0J, IBM VisualAge Smalltalk Enterprise requires the equivalent to Warp 4.0J Fixpack FX00004.
3.If you are using IBM VisualAge Smalltalk Enterprise on a DBCS system, you must use the ABTRULES.DBC file instead of the default US-English ABTRULES.NLS provided by the system. The ABTRULES.DBC file contains additional codepage conversion tables needed for the DBCS environment. You can find this file in your VisualAge NLS directory. Back up the ABTRULES.NLS file to ABTRULES.BAK, then rename ABTRULES.DBC to ABTRULES.NLS.

Using an English version of Lotus Notes

The NLS versions of Lotus Notes must be installed on the native Operating System (OS) platforms, in order for Notes to work. If a US-English version of Lotus Notes is installed on the native OS, then the user will not be able to input either SBCS or DBCS characters correctly. This is a restriction with Lotus Notes.

Web Connection does not support DBCS char for Cookies

DBCS cookies are not supported using the Servlet Interface. This is a limitation of the HTTP Server.

Display Resolution for DBCS machines

To ensure all information is displyed on your computer, we encourage you to use the highest resolution offered by your display terminal.

User-Supplied Code Page Conversion

A hook has been added to the VisualAge 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 which demonstrates usage of a custom code page routine.

Documentation and Helps

Information Center does not display with Mozilla 0.9.2.1

The Books Description page, http://localhost:57002/abtwebx/6.0/va/vabooks.htm , appears blank when viewed with Mozilla 0.9.2.1. To view the Information Center's Book Description page please use Netscape or upgrade Mozilla to the latest version.

On UNIX, Netscape 4.7 may not start automatically

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-UX and Sun Solaris, bring up Netscape manually before accessing the VisualAge Smalltalk Help. On AIX, bring up Netscape manually and type in the following URL :

http: //localhost:57002/abtwebx/6.0/va/vast.htm

Domino Connection

Domino Connection supported on Windows XP

The VisualAge Smalltalk Domino Connection feature is now supported on Windows XP when running with Lotus Notes V6.0.

EMSRV

Withdrawal of EMSRV support for Windows NT/2000/XP on SMP hardware

Running any release of EMSRV for Windows NT/2000/XP on a machine with more than one processor may lead to code repositories becoming corrupt. The increasing number of reports of corrupt code repositories resulting from running EMSRV in these environment has caused the following changes to be made to EMSRV:

EMSRV 7.0a (shipped only with VisualAge Java) and EMSRV 7.1 (shipped with VisualAge Smalltalk 5.5 and 6.0) -- if EMSRV detects more than one installed processor, it will report the following to the console (or to the Application Log if EMSRV is running as a service) and then exit:

WARNING: Running EMSRV for Windows NT/2000 on multiprocessor hardware is not supported due to the likelihood of a repository becoming corrupted.

EMSRV 7.1a (shipped with VisualAge Smalltalk 6.01) -- if EMSRV detects more than one installed processor, and the -mp command line option is not specified, it will report the following to the console (or to the Application Log if EMSRV is running as a service) and then exit:

WARNING: Running EMSRV for Windows NT/2000 on multiprocessor hardware is not supported due to suspected operating system bugs that may result in repository corruptions. Install and run EMSRV on a machine with a single processor or start EMSRV with the -mp option to bypass this check.

The check for SMP hardware can be bypassed by starting EMSRV with the -mp command line option. By doing this, you will be running EMSRV on an unsupported platform and must assume full responsibility if code repositories become corrupted. When starting with the -mp command line option, EMSRV will still report a warning to the console (or to the Application Log if EMSRV is running as a service):

WARNING: Running EMSRV for Windows NT/2000 on multiprocessor hardware is not supported due to suspected operating system bugs that may result in repository corruptions. You have chosen to start EMSRV with the -mp option to bypass a check that normally restricts EMSRV from running on multiprocessor hardware. This may cause repositories to become corrupted.

Note that EMSRV continues to support SMP hardware in all other operating system environments.

EMSRV 7.1a

EMSRV 7.1a and EMADMIN 7.0a are made available with this modification level. The changes from EMSRV 7.1 and EMADMIN 7.0 are as follows:

Platform Support -- the following additional operating system levels are supported by EMSRV 7.1a:
Windows XP Professional
Solaris 8.0
NetWare 6.0

Bug fixes:
Fixed bug in EMADMIN where a copy of a library would fail with an error if the size of the library in bytes was exactly divisible by 32768.
Fixed bug in EMSRV where in extremely rare conditions, connections with locks might be incorrectly terminated by the "EMSRV inactivity monitor". Such terminations would be accompanied by a warning message in the log but since the default behavior of EMSRV is only to report errors, these messages were not often seen.

On OS/2, Starting EMSRV

In an OS/2 environment, if EMSRV is installed under a directory name that contains spaces (e.g. x:\VAST60 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

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

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.

Installation

On Linux, client install may become unresponsive

We have seen rare cases where the client installation program on Linux will hang and become unresponsive after only partially completing the install. We have only noticed this on machines whose hard drive is one giant partition located at /.

If this happens, a safe workaround is to terminate the install program and completely delete everything in the /opt/IBMvast/6.0 directory. Then restart the install.

Select Features Screen in UNIX Installs

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.

On AIX, create a Journaled 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, increasing 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:

1. Direct connection to the Internet
2. Manual proxy

If you have selected an autoproxy from this menu, your attempt to access the VisualAge Smalltalk newsgroup will fail.

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

Fix to class variable initializer packaging rules for IC packaging

The fix to APAR PQ62227 introduced a change in packaging behavior for ICs. Previously, the #initializeClassVariable:to:inObjectNamed: and #initializeClassVariable:toObject:inClassNamed: packaging rules were being ignored. After the fix is applied, these packaging rules have their desired effect of initializing the identified class variable(s) in the packaged runtime IC. You should examine the senders of these messages in your code to ensure that they specified the initialization values that you want for the class variables at runtime.

XD packaging of non-MVS leaf ICs which use MPRs at runtime

When 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

HttpServer can't parse HTTP cookies with empty values

SstHttpCookie class>>valueAt:fromRequestHeaderString: walks back if it encounters a cookie with an empty cookie value.
Workaround: Modify SstHttpTokenizer>>#trimQuotes to guard against degenerate input.

    Replace: 
	^$" == s first
    With: 
	^(s size >1 and: [$" == s first])

HTTP server causes client to hang when server request exception handler generates exception

SstBasicServer>>processRequest: invokes SstHttpServer>>handleError:whileProcessing: during exception handling. This handler attempts to create an error page to be sent to the client, but triggers an exception when trying to create this error page if the request has not been initialized with a response header. This can occur if the exception occurs during request object initialization, and results in a client "hang".
The workaround is to:

Move initialization of the response header

  • Delete SstHttpServer>>#basicProcessRequest:
  • Implement SstHttpServer>>#processClientRequest: as follows.
        processClientRequest: request
            request header responseHeader: (self defaultResponseHeaderFor: request).
            ^super processClientRequest: request
    

Http proxy exception list can't handle more than 2 components

SstHttpUrl>proxyExceptionList:excludes: uses #sstSplitAt: to parse the exception list, but #sstSplitAt: only allows for two substring components. So, a list with more than two components is parsed incorrectly.
The workaround is to send #subStrings: instead of #sstSplitAt: in SstHttpUrl>proxyExceptionList:excludes:

SST IIOP Support is Obsolete

CORBA IIOP facilities provided by SST in previous releases are obsolete as of this release. The implementation provided in previous releases continues to be shipped with this release, but all methods have been recategorized as 'OBSOLETE'. There will be no further developement or enhancement of these facilities, and they may be removed from the product in a future release.

Customer applications which made use of these facilities in a previous release will continue to be supported as they are migrated to this current release.

Customers are advised to make use of Web Services technologies, such as XML and WSDL, for future interoperability strategies.

Performance improvement in writing walkback log

In previous releases of VisualAge Smalltalk Server Runtime, only one method of logging a simple walkback was provided. When an error occurred, the walkback information was written to TranscriptTTY. This caused the walkback information to be written to the console (Unix) or to a log file identified by the -l commandline option. Since TranscriptTTY does unbuffered character-at-a-time output, it can be very time consuming to write the walkback information.

For VisualAge Smalltalk V 5.5.2 and later, an alternative output mechanism is provided. When it is enabled, this mechanism writes the walkback information to a file stream just as would be done for a Reduced Runtime image. This is a buffered operation which can be more than an order of magnitude faster than writing to TranscriptTTY.

To enable writing the walkback information to a file stream, you must provide the startUp class with the filename of the file to be associated with the file stream. For example, to see the difference in behavior, create an XD image and load the HelloWorld application. Then package it specifying AbtHeadlessRuntimeStartUp as the image startup class. If you specify HelloWorld haltHelloWorld as the application entry point, the walkback will be written to TranscriptTTY (you need to specify the -l commandline switch at runtime to see this output on Windows and OS/2); if you specify System image startUpClass walkbackFileName: 'runtimeWB.log'. HelloWorld haltHelloWorld as the application entry point, the walkback will be written to the runtimeWB.log file.

Support for JDK 1.3 using RMI

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

IIOP PingPong examples fails 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.

5.0 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 for OS/390

SST HTTP Server walks back in initialization of a new client socket

SstUtfSocketStream>>initializeOn: fails to initialize buffer size inst vars prior to use, resulting in the exception 'Primitive failed in: Behavior>> #new: due to Invalid class in argument 1'. Workaround: Add a send of #getBufferSizes before the send of #allocateBuffers, as shown below.

    self getBufferSizes; allocateBuffers
  

Web Connection

Debugging Web Connection applications using 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>>#handleTransaction: method, change the ExAll exception reference to ExError.
2.In the AbtWebServerInterfaceBaseApp>>Block>>#abtWsiAtEndOrWhenExceptionDo: 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 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.

Web services

Unnamed attribute mapping cannot be resolved for SOAP request

Attribute mappings of the form below are intended to extract the simple content from an XML element that contains both attributes and simple string data. Problems can occur for SOAP messages because the attribute mapping lookup has an unnecessary reliance on the namespace of the attribute. Since there is only one unnamed attribute mapping for each type mapping, namespace verification is unnecessary and can cause failed lookups.

 <AttributeMapping SetSelector="value:" GetSelector="value">
   <Attribute></Attribute>
 </AttributeMapping>

The fix for this problem is shown below:

AbtXmlMappedObject>>#initializeSimpleContent:withAttributes:
initializeSimpleContent: anObject withAttributes: anAttributesDictionary
	" The element being processed contains simple content (ie. just string data; no subelements ) "

	| attrMap |
	self mapping notNil
		ifTrue: [
			attrMap := self mapping attributeMappingNamed: ''.
			attrMap notNil
				ifTrue: [
					self setAttribute: self elements first
						inObject: anObject 
						withAttributes: anAttributesDictionary
						usingMapping: attrMap ]]

SOAP Packaging Walkback

The walkback 'String doesNotUnderstand abtAsStream' occurs in packaged runtime images when processing SOAP messages that contain SOAP array structures. The workaround is to either include the application AbtRecordStructureBaseApp in the packaged runtime image, or modify the method SstSoapArray>>#setDimensionsForArrayTypeString: as shown below.

     setDimensionsForArrayTypeString: aString
	| typeDims contentDims |
	typeDims := self parseDimensionsFrom: ( ReadStream on: aString).
	contentDims := self dimensionsOfContents.
	1 to: typeDims size do: [:anIndex |
		typeDims at: anIndex put: ( contentDims at: anIndex) ].
	self dimensions: typeDims

Missing Method, #abtXmlNoOp, causes Walkback in reduced runtime image

Walkback in reduced runtime image due to missing method #abtXmlNoOp. The walkback occurs during intialization of the XML resource cache at image startup time. The workaround is prior to packaging, implement the class method #packagerIncludeSelectors in the class AbtXmlSerializationBaseApp as shown below.

     packagerIncludeSelectors
	"Define rules for the given packaged image."
	^#( abtXmlNoOp )

Server Fault message construction

When a Web services client receives a SOAP fault response from the server, standard Web services handler chains are traversed prior to signalling an exception to report the SOAP fault. Therefore, fault chains are traversed after standard client processing has already completed. Custom client chains may need to be aware of the possibility that the message result could be a fault. Ideally, the Web services support should circumvent standard processing and branch immediately into the fault handlers after discovering a SOAP fault in the output message.

Client handlers can use the message #isSoapFault to verify that message results contain expected content.
example: fault := anSstWSMessageContext results detect:[:each | each isSoapFault] ifNone: [ ].

XML

XML schema parsing does not handle sequential <include> elements

Parser does not work properly when multiple XML schema "include" elements are parsed sequentially. The problem occurs because the #addSchema: selector of AbtXmlSchema is not coded to handle a collection of schemas. When multiple 'include' statements are encountered sequentially, the resulting XML schemas are converted to a collection by the parser. When mapping into the AbtXmlSchema, the #addSchema: method is passed a collection. The workaround is in AbtXmlSchema to add/replace the following methods:

     addSchema: aCollectionOrAbtXmlSchema
	" An embedded  tag was found.  This occurs when processing an 'include' or 'redefine' tag.
	If the target namespaces match, add the content of the passed schema to this schema; otherwise,
	add @anAbtXmlSchema as normal content.
	The incoming argument may be an individual schema or a collection because two or more 'include' elements 
	may appear concurrently. "

	aCollectionOrAbtXmlSchema abtIsSequenceableCollection
		ifTrue: [ aCollectionOrAbtXmlSchema do: [:anAbtXmlSchema | self primAddSchema: anAbtXmlSchema ]]
		ifFalse: [ self primAddSchema: aCollectionOrAbtXmlSchema ]

     primAddSchema: anAbtXmlSchema
	" An embedded  tag was found.  This occurs when processing an 'include' or 'redefine' tag.
	If the target namespaces match, add the content of the passed schema to this schema; otherwise,
	add @anAbtXmlSchema as normal content "

	anAbtXmlSchema targetNamespace = self targetNamespace
		ifTrue: [ anAbtXmlSchema content do: [:aContent | self addContent: aContent ]]
		ifFalse: [ self addContent: anAbtXmlSchema ]

Suppress serialization of nil attribute values when attribute mapping specifies Required="false"

This change does NOT affect objects that utilize an XML schema for serialization.
Nil attribute values are now suppressed during serialization of attributes with attribute mappings that specify 'Required="false".

For example:

<ClassElementMapping ElementTagName="customer" ClassName="AbtXmlSampleCustomer" >
<AttributeMapping ClassAttribute="lastName" Required="false"><Attribute>lastName </Attribute>
</AttributeMapping>
</ClassElementMapping>
If the lastName attribute of a serialization target object is nil, the serializer will not render the 'lastName' attribute.

XML - minOccurs default value in AbtXmlSchemaElement changed to 1

The default value for the #minOccurs setting of an AbtXmlSchemaElement was changed from 0 to 1. This is now in compliance with the W3C schema specification. When creating an XML schema element that is not required by it's parent element, specify a value of "0" for the minOccurs attribute in the schema element definition.
ie)
<xsd:element name="globalNamespace" type="xsd:string" minOccurs="0" />


The setting of the minOccurs attribute affects XML serialization/deserialization.

An XML element with nil value and minOccurs="0" will not be rendered in the XML stream.

An XML element with nil value, minOccurs="1", and nillable="true" will render as shown below:
<globalNamespace xsi:nil="true"></globalNamespace>

An XML element with nil value and minOccurs="1" and nillable="false" will render as shown below:
<globalNamespace></globalNamespace>

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/6.0/xml to the newly created xml directory. For example:
cd /xml
cp /opt/IBMvast/6.0/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.

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 (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 to code page 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 2002. All rights reserved.

601-49f