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.
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.4, follow these steps: 1. If EMSRV is running from the directory to be updated, stop EMSRV. 2. Stop any running VisualAge Smalltalk images.
If you have a version prior to VisualAge Smalltalk Version 6.0.4 installed, please refer to the Migration Guide for important information before using VisualAge Smalltalk Version 6.0.4. 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.
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.
PQ45824 - ABRREMOVEINTERESTFROM: DOES NOT WORK FOR PROMOTED FEATURES
PQ46370 - SCI Sockets connot send buffers that are 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 - Running out of sockets on Windows
VisualAge Smalltalk V6.0 lets programmers create and deploy e-business applications that are cross-platform, object-oriented, and integrated with IBM's key initiatives: - Build and deploy enterprise Web service solutions for dynamic e-business using VisualAge Smalltalk. - Protect communication transactions with Secure Socket Layer (SSL) support - Asynchronous call-out on all deployment platform including OS/390, z/OS, HP-UX, and Red Hat Linux. - Server Workbench now part VisualAge Smalltalk Enterprise - Updated currency of databases, communication protocols and Java integration - New support for Red Hat Linux, Windows XP and Windows ME
PQ08131 - ORGANIZER->TOOLS->FIND OK DEFAULT DOES NOT WORK
PQ48172 - WINDOW REDRAW PROBLEM WHEN THE WINDOW INCLUDES RADIO BUTTONS
AND ALLOWSHELLRESIZE SET TO 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
PERFORMANC
PQ66012 - XML TEXT ELEMENT WRITING EXTRA SPACES
PQ66546 - Walkback using Alt+key for OLE windows with no VAST menu
PQ68418 - Changing ATTRIBUTE of a column results in error
PQ68958 - Container Details Tree - 'UndefinedObject does not understand
left'
PQ69438 - MQRC_SELECTOR_ERROR DOING A ABTMQCALL>>INQUIRE:
PQ69439 - "EXCEPTION ::CORBA::MARSHAL" WHEN PERFORMING A "LIST:BL:BI"
PQ69441 - "EXCEPTION ::CORBA::INTERNAL"
PQ69522 - XD PACKAGING INSTRUCTIONS DO NOT INCLUDE NEEDED APPLICATIONS
PQ69539 - CAN NO LONGER EDIT PACKAGING INSTRUCTION DESCRIPTION FROM THE
PQ71155 - Walkback in EwTableList>>exposeHeading:
PQ72134 - MULTIPLE EXCEPTION HANDLING ERRORS
PQ72175 - ORA-01036 ILLEGAL VARIABLE NAME/NUMBER - INSERT INTO ORACLE8
PQ72976 - AbtXmlDOMFactory class>>#newText: causes walkback
PQ73160 - EwSpinButton>>removeEditPolicyEv
entHandler:receiver:selector:clientData: code incorrect
PQ73400 - ABTSOCKETSTREAM>>RECEIVEINTOBUFFER: BUFFERSIZE:TIMEOUT: -
WRONG TIMEOUT VALUE
PQ74442 - WALKBACK WITH NON-FATAL SST ERROR ECONNRESET - CONNECTION
RESET
PQ74509 - ORACLE ERROR 17099 RESULTING FROM INCORRECT SUPPORT FOR
THREADED CALLS TO ORACLE.
PQ74835 - SST IS MISSING THE CAPABILITY FOR TUNNELING SSL THROUGH HTTP
PQ75358 - ABTIBMCLIDATABASECONNECTION>>NOTFOUNDERRORCOLLECTION RETURNS
AN ARRAY WHEN IT SHOULD RETURN AN ABTORDEREDDICTIONARY
PQ75471 - ABTDATABASEQUERYEDITPART>>#REFRESHCOMPOUNDTYPE REFERENCES
UNIMPLEMENTED METHOD DEFAULTERRORBLOCK
PQ75763 - ABTORACLE8DATABASECONNECTION TABLEORVIEWEXISTSNAMED: ALWAYS
RETURNS TRUE
PQ76322 - CFSPATH>>FILEENTRIESMATCHING: DOES NOT USE PATTERNTOMATCH
INPUT
PQ76487 - ABTMQSERIESBASEUNIXSUBAPP CLASS>>BUILDSHAREDLIBRARYTABLE - AIX
PQ76560 - Error converting a float from MVS hex format to IEEE format
PQ76674 - V6.0.1 #LITERALINDEXFOR: CHANGE CAUSES DIFFERING IDENTITY
PQ77138 - RUNNING DATABASE QUERIES ON ORACLE 8.1.6/SUN8 CAUSES SYSTEM
HANG
14069 - Mq call #createDefaultMessage... causes walkback on UNIX
14409 - Method categorization
14410 - Native translation fails on cobra
14429 - SciSslSocket>>sslInitialize: walks back in
#primitiveAsyncCallSetup: if certificate file cannot be found
14430 - References to class AbtIbmDatabaseManager need to be updated
14432 - callSSL_shutdownWith: walks back in callWithSslErrorCheck:
error block.
14514 - Support multiple SOAP body entries.
14558 - Enable serialization of SOAP encoded messages as multi-reference
14610 - SstUrl needs API for Server-based Naming Authority.
14620 - OSStringZ is misplaced in prereq chain
14666 - SciSslBlockingDispatcher>>#callRecvWith:with:with:with:
14899 - SstSocketStream>>close fails to protect against close if closed
14948 - SSLInterface should support certificate chain files
14953 - SST - getPathInfo behavior not consistent with Servlet API
14970 - Deployment fails when mapping exceptions enabled
14976 - Deployment of XML schemas via VAST Web services deployment
descriptor
14992 - Walkback in reduced runtime due to missing selector #abtXmlNoOp
14996 - Support for XML schema 'default' setting
14994 - HTTPServer request exception handler generates exception
14995 - Http proxy exception list can't handle more than 2 components
15002 - Runtime resolution of bindingOperation fails when no port is
specified as part of URL
15005 - String>>#asAtom API missing
15006 - <choice> element content must be optional
15007 - Need big/little endian methods on ByteArray
15008 - xsi:type for SOAP arrays should always be 'Soap-env:Array'
15010 - Improved serialization of inherited types
15011 - Enable seamless serialization/deserialization of
KeyedCollections
15014 - Refactor XML serialization code
15015 - Refactor XML deserialization code
15016 - Window redraws every time it is scrolled
15017 - SOAP deserialization should be 'lax' when processing sequences
15019 - Improved handling of XML schema 'anyType'
15020 - Float exceptions in #float32At:put: not reported correctly(Win)
15021 - DateAndTime class>>sstMinutesFromUTC missing return
15024 - Dates do not properly deserialize when defined as DTD attributes
15026 - CHANGING THE ATTRIBUTE OF A COLUMN RESULTS IN CONVERTER ERROR
15027 - #abtXmlMappedObject for unmapped wrapper elements
15028 - DateAntTime class>#abtXmlFromString: does not properly handle
'z' time zone indicator.
15031 - XML schema 'import' support
15032 - #validate switch of AbtXmlDeserializationConfiguration always
answer true
15033 - Illegal characters not escaped in XML attribute values
15034 - Better error messages for PlatformFunctions
15036 - XML schema serializer improvements
15035 - Enable code page conversion of serialized SOAP messages
15039 - XML serialization performance improvements
15041 - Some selectors missing from schema type objects (ie. #final and
#lang)
15042 - #abtXmlInitializeSchemas should use custom parser configuration
15043 - Default stack size too small for aco threads
15044 - Performance improvements for AbtXmlMappingParser
15045 - win odbc libname should be odbc32
15046 - Walkback when serializing XML schema <choice> elements
15048 - Array class>>#withAll: fails with a walkback
15050 - Need to update VM to 6.0.2
15057 - Error serializing complexType multi-ref with nil value
15059 - Missing class for WSDL 'headerfault'
15060 - Error when including compiler in XD image
15061 - Support for WS-I Basic Profile
15064 - Mapping DTD 'abtxmap.dtd' should be automatically loaded into
XML object cache
15066 - Simplify client processing for 'soap:header' WSDL entries
15069 - Enable client authentication for SSL server
15071 - Enable spec of a CA trust store for client validation of server
15072 - ORA-01036: illegal variable name/number
15073 - Subapplication class>>#loaded in wrong app
15074 - MessageNotUnderstood exception has no implementation
15075 - SubApplication class>>#kernel..... methods should be removed
15076 - doesNotUnderstand broken after fix for 15074
15077 - No deployment error reported on endpoint startup failure
15079 - Support for WSDL 1.1 headerfault elements
15080 - AbtXmlDtdOutputSerializer not included automatically in reduced
runtime
15081 - SOAP:Array serialization for 'Set' objects
15082 - Enable facet validation for Character objects
15083 - Suppress validation for nillable elements that contain nil
values
15085 - DdeImplementationSupport specifies pool outside prereq chain
15086 - Pasrsing support refactoring
15087 - Error deserializing 'nil' value for base64Binary field
15088 - Improve processing of deployment extensions
15089 - Support 'transportMappings' at deployment time
15090 - Base changes to better support emerging specifications (ie.
OGSI)
15091 - Headless app that makes heavy use of aco hangs on NT SMP box
15092 - SSL error handling sometimes returns bogus errors
15093 - Make SstWSServlet pluggable in SstWSHttpNetworkTransportStrategy
15094 - SciSslSocketConfig shouldn't call cleanRegistry on shutdown
15097 - Confusing comment in Time class >> #millisecondClockValue
15098 - Separate processing for contiguous 'any' type elements
15099 - Better support for elements separated by whitespace
15102 - Basic support for WS-Security
15103 - Unexpected walkback when validating enumeration value against
schema
15104 - Wrong version in line up for AbtThreadsApp
15106 - HTTP/1.1 - Chunked Transfer Encoding
15107 - Missing selectors from sstaxis.map from reduced runtime
15108 - sciPing fails if inet addr not in DNS
15109 - Stepping through "6 halt printString" causes crash
15110 - Basic support for SOAP 1.2 specification
15114 - primitiveGetSciSslContext returns before peer cert verify
15128 - DB2 bigint field does not work properly
PQ79198 - Stored procedure with a DECIMAL(1,0) followed by a CHAR(1)
causes melt
PQ79199 - Stored procedure with VARCHAR I/O has incorrect result when
the length of the input is shorter the 2nd time it's called
PQ79782 - V4.5 App exported to V6.0 has old connection names and
generates incorrect archival code in V6.0
PQ83002 - AbtTopLevelPartBuilder DNU minMaxDisplayPolicy:propertyData:
when opening container column property view
PQ83467 - Mapping Smalltalk to Java classes in RMI must be in strict
ASCII ascending order
PQ85465 - Upgrading to AIX 5.X with VAST 6.0.x causes hang in the VM
PQ86060 - Core file occurs on Solaris when using UNIXProcess>>#shell:
PQ87760 - Receiving CLI0112E when trying to update/change a big int
field
PQ89279 - UndefinedObject DNU #setRcForHierarchyIndicator
PQ89564 - Provide notification on ACO shutdown
PQ90424 - CompiledMethod>>#equals: gets 'Out of Range' primitive error
PQ90699 - System Transcript File -> Print gives truncated list of
available printers
PQ92336 - Client calls to SstHttpServer hangs client request
PQ92913 - AbtIbmStaticRunTimeServices method messageAPIName incorrectly
spelled
PQ95443 - AbtPortableNotebookPageView #aboutToBeSwitchedTo and
#aboutToBeSwitchedFrom events mis-sequenced
PQ95531 - EwComboBoxEditPolicy works in development but not run time
PQ98766 - Inconsistent handling of milliseconds in AbtTimestamp
14964 - Walkback in CoIteratorProcessor>>#hasProducedLayout 15121 - Parser performance improvements 15137 - Iconv output buffer size too small in convertLocalCpToUtf: 15138 - AbtWsiServerMonitor>>#refreshProcess returns invalid value 15139 - Schema element cannot resolve it's type 15140 - AbtError>>#display gives bad output 15141 - AbtError>>#display can wb w/ "receiver must be a boolean" 15143 - Add ApplicationManager app/class filtering 15144 - WB when disconnecting db before closing win with multirow query 15146 - Eliminate dialog sample code 15147 - Error in AbtMQCNOStruct>>#conntag 15149 - Multiple timerThreads on UNIX in certain circumstances 15148 - Some ODBC drivers do not return the error codes VAST expects 15150 - Must mark JIT code space as executable on Windows 15151 - AcoResourceManager defaultStackSize on AIX should be increased 15153 - Update OSWidget to support automated testing 15157 - Directed Message in AcoFutureStub not reinitialized 15158 - Error in SstInvocationHandler>>ddefaultRequestExceptionHandler 15159 - Web browser client hangs when multiple GETs are done 15160 - Update copyrights, bitmaps, and strings to 6.0.3 15161 - CoroutineFuture is nil when unlocking Thread in Process 15162 - SstWebServicesHttpSupport ref Pool Dict not pre-req'ed 15163 - Typo in AbtSelectedSet>>newCommonPopUpMenu: 15166 - CwPrinterShall>>#createDocInfoStruct wrong 15167 - DateAndTime class>>#now and AbtTimestamp class>>#now incorrect 15168 - CompilerError>>#sourceString: wrong 15170 - Add tracing to the SCI DLL 15174 - Missing Windows message handlers at runtime
PK21642 - AbtContainerDetailView incorrectly displays heterogeneous data
PK23422 - AbtComboBox gives walkback when maxlength is set on Unix
PK23487 - Intermittent slowdown under heavy load on Unix
PQ93000 - AbtMQqm>>#terminate - dictionary concurrency problem - not
thread-safe
7990 - Embedded Shell menubar item translateCoords wrong
8956 - Integer>>#even method has poor performance
13967 - HY024 returned on multi-row ODBC operations with DB2
14445 - Block>>#critical should be categorized as API
15118 - FromDLL test in CgIconTests fails on Windows
15119 - Multiple examples fail due to bitmapPath being an array
15175 - Messages missing in AbtDirectoryPrompter
15177 - Integer>>#bitAt:put: wrong
15178 - SciSocketManager>>#getHostName passes bad parameter
15179 - Error in implementation of AcoResourceManager active setting
15181 - Scaling a transparent GIF causes it to lose transparency
15184 - UNIXProcesses class>>#setUpApplication has redundant
toBeLoadedCode
15185 - Invalid characters in SCI trace filename
15186 - Swapper mutation of AbtTimestamp fails
15190 - AbtTimestamp wrong for dates earlier that 1901-01-01
15192 - AbtTimedWait is not threaded on Windows
15195 - Missing documentation for 64-bit integer support
15198 - Support more than 2GB RAM on Windows
15199 - Remove obsolete OS400 subapplications
15200 - Inspector has focus on 'Bind to self' checkbox, not items in
the list
15213 - Improve SCI trace output
15215 - Versioning/releasing owned parts in Organizer causes a walkback
15216 - AbtPortableNotebookPageView broken for some users by V6.0.3
15218 - Broken link to ResHacker in IBM Smalltalk User's Guide
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.
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.
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=")"
In V6.0.3, code was changed in AbtPortableNotebookPageView so that invoking the aboutToBeSwitchedTo event was not deferred. This aligned its implementation with aboutToBeSwitchedFrom which is also not deferred. Before this change was made, if a user quickly clicked on more than one notebook tabs which had associated events, the events could be run out of order. For example, if Page2 has both these events connected, and if a user is on Page1 and rapidly clicks first on the tab for Page2 and then on the tab for Page3, the events could be run in the order switchFrom Page2, switchToPage2. This is obviously incorrect behavior. Unfortunately, some user applications depended on the deferral of execution of the aboutToBeSwitchedTo event. For example, it could be used to set focus to a particular subpart of the notebook page when the tab for the page was selected. These application were broken by the change. Since it is not possible to automatically satisfy the needs of both sets of applications -- those that depend on execution deferral and those that depend on no execution deferral, another solution is needed. One possible solution for these broken applications is to change their implementation so that the aboutToBeSwitchedTo handler does the deferral of execution itself if needed. So a method that needs this capability and that used to look like this: aboutToBeSwitchedTo: aComp aComp setFocus whould be rewritten as: aboutToBeSwitchedTo: aComp [aComp setFocus] abtDefer Another solution is to return the system's implementation to the old (deferral of execution) behaviour. This can be done by changing the the value of following line in the .INI file from false (6.0.3 behavior) to true (6.0.2 and previous behavior): [Version Compatibility] deferPortableNotebookPageSwitchToCallback=false
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.
There is an error in the IBM Smalltalk Programmer's Reference sample
code for Common Widgets event handlers. The following changes are
needed:
Programmer's Reference Guide
--
Chapter 7: Common Widgets
--
Creating and Using Widgets
--
Event handlers
--
Labels should be sent as the clientData when adding the drawing
eventHandler:
drawing
addEventHandler: ButtonPressMask | KeyPressMask | PointerMotionMask
receiver: self
selector: #eventHandler:clientData:event:
clientData: labels.
In the eventHandler method, labels needs to be declared and assigned
from to the clientData argument:
eventHandler: widget clientData: clientData event: event
"Handle an input event."
| labels |
labels := clientData.
event type = MotionNotify
"etc."
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]].
...
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
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.
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'
This will act very much like the user break mechanism. When the VM process receives a SIGTERM, it will post a directed message into the image that will cause EmSystemConfiguration >> #terminate to execute. The behavior of #terminate is determined by the start up class, and the default action is to execute "System exit". Although the Smalltalk code that sets up the termination behavior will be available on all platforms, MVS and UNIX are currently the only platforms in which the VM will generate the terminate message. Documentation: Add the following section in the Server Guide under Developing server applications->Preparing applications for cross development->Developing applications for native server environments->Making applications headless. This new section should follow the first paragraph, which ends with the sentence "The System exit lets the runtime environment know that the user application is finished processing." Mark the section as UNIX only (i.e. with a big red X). The traditional and standard lightweight sysadmin graceful process termination mechanism on UNIX platforms has long been the sending of a SIGTERM signal. When the Smalltalk virtual machine receives this signal, it causes the directed message residing in the class variable TerminateMessage of the class EmSystemConfiguration to be sent. By default, this will execute System exit. You can override this behavior to add shutdown code that is specific to your application by executing System terminateMessage: yourDirectedMessage. Typically, when you customize your own TerminateMessage, its last statement will be System exit. Use the UNIX kill command line utility to send the SIGTERM signal to your Smalltalk process. The kill command needs only one argument when sending SIGTERM -- the process ID (pid) of the process to be signalled. The Smalltalk VM will print out its pid to the standard output stream when it comes up. For example, if the pid of your Smalltalk VM is 12345, you can gracefully bring this VM down from a UNIX shell prompt with the command: kill 12345
Support for ANSI Smalltalk (see ANSI/NCITS 319-1998 Smalltalk
Programming Language, available in PDF format from
http://www.techstreet.com/cgi-bin/detail?product_id=56122) 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:
1. The following Exception methods are not functional
- isNested
- outer
- pass
- resignalAs:
- retry
- retryUsing:
2. The following DateAndTime methods are not functional:
- timeZoneAbbreviation
- timeZoneName
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.
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 documentation 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 character 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:
Arguments that are not referenced in the template string are ignored.
Template string references to missing arguments are replaced by the
escape sequence itself.
4) Replace the last entry in the "Resultant message" column of Table 49
with the following:
'Missing arguments are %2.'
Problem:
1. Resumable execption instance variable not set (should answer an
empty collection)
Exception withAllSubclasses
select:
[:each |
each exceptionalEvent resumable isNil]
2. defaultHandler instance variable not set (should answer an empty
collection?)
Exception withAllSubclasses
select:
[:each |
each exceptionalEvent defaultHandler isNil]
3. 3rd (and after) element, of the contents of
ExceptionalEventCollection, is the Exception subclass and not an
instance of ExceptionalEvent (should answer false)
(MessageNotUnderstood, Error, Warning)
ancestorOf: Notification exceptionalEvent
4. Sample below should answer nil (same as Notification signal) but
instead executes the exception block although Notification does not
inherit from Error (should answer nil).
[Notification signal]
on: Error
do: [:error | error exitWith: 'Not Okay']
Examples:
All the following (non comment) expressions should answer true when
evaluated.
"Class based exception problems"
([Notification signal. 'Hello' ]
on: Warning, ZeroDivide, Notification
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([Notification signal. 'Hello' ]
on: Warning, ZeroDivide, Notification
do: [:error | error return: 'Goodbye']) = 'Goodbye'.
([ZeroDivide signal. 'Hello' ]
on: Warning, ZeroDivide, Notification
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([ZeroDivide signal. 'Hello' ]
on: Warning, ZeroDivide, Notification
do: [:error | error return: 'Goodbye']) = 'Goodbye'.
([Notification signal. 'Hello']
on: Error
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([Notification signal. 'Hello']
on: Error
do: [:error | error return: 'Goodbye']) = 'Hello'.
([Notification signal. 'Hello']
on: Warning
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([Notification signal. 'Hello']
on: Warning
do: [:error | error return: 'Goodbye']) = 'Hello'.
([Object new not foo. 'Hello']
on: Error
do: [:error | ^true]).
([Object new not foo. 'Hello']
on: Error
do: [:error | 'Goodbye']) = 'Goodbye'.
([Object new not foo. 'Hello']
on: Error
do: [:error | error return: 'Goodbye']) = 'Goodbye'.
([Object new not foo. 'Hello']
on: Error
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([Notification signal. 'Hello']
on: Notification
do: [:error | error pass]) = 'Hello'.
([Warning signal. 'Hello']
on: Notification
do: [:error | error resume: 'Goodbye']) = 'Hello'.
([Warning signal. 'Hello']
on: Notification
do: [:error | error return: 'Goodbye']) = 'Goodbye'.
Solution:
The ANSI exception handling code has been reworked as a result of this
defect.
Two aspects of this code update may cause customers who work outside
the scope of the identified API method some concern:
1) It was discovered that an erroneous Exception class>>#signal: API
method was provided. This protocol is not defined by the ANSI
Specification. Therefore, although the method was left in place, it
was commented appropriately and recategorized to 'ANSI-Obsolete'
meaning that its use is depricated.
2) The attempt to homogonize the old and new forms of exception
handling simply won't work. Undoing this failed attempt results in the
following changes:
-- The creation and extension of ExceptionEventCollection for
class-based exceptions is removed and replaced by the creation and
extension of a new ExceptionSet class. Since there was no explicit
API for creating instances of these collections, this should be a
generally transparent change. In addition, all instance-side ANSI-API
has been moved from ExceptionalEventCollection to ExceptionSet since
ExceptionalEventCollection no longer supports holding ANSI-style
exceptions.
-- The Block>>#on:do: method is changed to handle ONLY ANSI-style
class-based exceptions. Handling the old style instance based
exceptions was an undocumented extension of function in this method
that is now eliminated.
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).
Due to a subtle change to the compiler, some methods, when recompiled,
may behave differently in 6.0.1 and 6.0.2 than they did in earlier
versions.
The original problem involved an error in the way the compiler
determined whether 2 array literals were identical when the array
literals contained one or more numeric values. See badArrayIdentity
below as an example.
This problem was corrected in 6.0.1, but some unforseen side-effects
were introduced as shown in the table below. These side-effects have
been eliminated in 6.0.2.
While testing the changes for 6.0.2, we discover and fixed another
(pre-existing) problem in this same code as demonstrated by
poolDictionaryModification below.
badArrayIdentity
| a |
a := #(3.0).
^a == #(3) "Should answer false"
stringLiteralIdentity
| a |
a := 'hello'.
^a == 'hello' "Should answer true"
mixedArray
|a|
a := #('string' #symbol 3).
^a == #('string' #symbol 3) "Should answer true"
poolDictionaryModification
"Upon method compilation, both constants = 'y'"
"Upon entry to this method, TestPoolB::Value1 = 'y'"
TestPoolA::Value1 := 'x'.
^TestPoolB::Value1 "Should answer 'y'"
6.0.0 6.0.1 6.0.2
badArrayIdentity true false false
stringLiteralIdentity true false true
mixedArray true false true
poolDictionaryModification 'x' 'x' 'y'
The Block>>#critical method is commonly used to ensure single-threaded execution of a section of code even though it is not categorized as API and is not documented. The following documentation is added and the method is recategorized as CPM-API. The IBM Smalltalk Programmer's Reference needs to be updated. The affected pages are: * 48, Block evaluation methods, Protocol synopsis, Block evaluation methods critical Evaluates the receiver (a zero-argument block) and guarantees that there will be no context switch while the receiver is being evaluated. Answers the result of the last statement to be evaluated.
The following documentation updates are associated with 64-bit integer
support. Note that this is not a functional change to the product,
just documentation for already existing function.
The IBM Smalltalk Programmer's Reference needs to be updated to include
PlatformFunction support for 64-bit integers. The affected pages are:
* 286, IBM Smalltalk C programming model, Defined types:
U_8, U_16, U_32, U_64
Unsigned 8-, 16-, 32-, and 64-bit integers
I_8, I_16, I_32, I_64
Signed 8-, 16-, 32-, and 64-bit integers
* 289, External language interface, Parameter types:
int8, int16, 1nt32, int64, uint8, uint16, uint32, uint64
If used as a parameter type, the parameter must be an Integer that can
be represented in 32 or 64 bits, Character, Boolean, or nil (see Passed
parameters). Instances of OSObject with reftype immediate (namely true,
false, nil, Characters, and SmallIntegers) can also be used (see
OSObjects). If used as a return type, the low n (8, 16, 32, 64) bits of
the return value are sign- or zero-extended (signed or unsigned,
respectively) and then converted to a Smalltalk Integer. The return
value in Smalltalk is guaranteed to be within these given ranges:
int8
-128...127
int16
-32768...32767
int32
-2147483648...2147483647
int64
-9223372036854775808...9223372036854775807
uint8
0...255
uint16
0...65535
uint32
0...4294967295
uint64
0...18446744073709551615
* 290, External language interface, Passed parameters:
All values passed to C functions are extended to a 32-bit quantity
before being passed (except for int64 and uint64 which are passed as
64-bit quantities). Signed integers are sign extended; unsigned
integers are zero extended. Because the C compiler does the same thing,
it will be transparent to you.
* 295, Entry points, Parameter types and return types
int8, int16, int32, int64, uint8, uint16, uint32, uint64
If it is used as a parameter type, the low 8, 16, 32 or 64 bits of the
parameter are converted to an Integer that is in the specified range.
If it is used as a return type, the return value must be an Integer
(see Returned parameters). The integer ranges are as follows:
int8
-128...127
int16
-32768...32767
int32
-2147483648...2147483647
int64
-9223372036854775808...9223372036854775807
uint8
0...255
uint16
0...65535
uint32
0...4294967295
uint64
0...18446744073709551615
* 296, Entry points, Returned parameters
All values returned to external language functions are extended to a
32-bit quantity before being returned (except for int64 and uint64
which are passed as 64-bit quantities). Signed integers are
sign-extended; unsigned integers are zero-extended. All the int types
perform the same conversion when converting from IBM Smalltalk objects
to external language values. For example, -1 can be returned as a
uint32 or a uint8. Both result in 0xFFFFFFFF being returned.
* 309, OSObject subclasses, OSBaseType
OSBaseType
You use subclasses of OSBaseType to represent pointers to C base types.
Dereferencing an OSBaseType answers a Smalltalk immediate type. All
subclasses of OSBaseType have indirection level one. To model int * (a
pointer to a C array of int), use the class OSInt32. Dereferencing an
instance of OSInt32 results in a signed Smalltalk integer. IBM
Smalltalk provides the following standard OSBaseType subclasses:
OSBool8, OSBool16, OSBool32
OSChar8, OSChar16
OSFloat32, OSFloat64
OSInt8, OSInt16, OSInt32, OSInt64
OSUInt8, OSUInt16, OSUInt32, OSUint64
OSVoid
The executables (abt, nodialog, esvio, abtntsir, and abtntsrv) are linked with the /LARGEADDRESSAWARE switch so that more than 2GB of memory can be referenced if the Windows environment is setup properly to support such access. For information on how to setup the Windows environment to support this capability, see the MSDN article titled "4GT RAM Tuning" (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/memory/base/4gt_ram_tuning.asp).
By default, the send and receive buffers used for local sockets are set at 32 KB (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.
Support has been added for MQSeries on Linux and HP-UX platforms.
VisualAge Smalltalk Enterprise does not support APPC and CPIC on Solaris, HP-UX or Linux.
The Secure Socket Layer (SSL) support for VisualAge Smalltalk uses OpenSSL binaries. OpenSSL is 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 at the end of Chapter 13. SSL in the IBM Smalltalk Programmer's Reference. The SSL feature is supported on Windows, Linux, AIX, HP-UX, and Solaris. The SSL feature is not supported on MVS and OS/2 platforms.
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.
Support for MQCONNX and MQBEGIN function calls, along with their associated options and structures has been updated. MQCONNX is similar to MQCONN except that it allows options to be specified that controls the way the call works. The AbtMQBOStruct allows the application to specify options relating to the creation of a unit of work. The structure is an input/output parameter on the MQBEGIN call. The AbtMQBOStruct is not available for MQ clients. Refer to MQSeries documentation for further information about these functions and structures.
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 hte
AbtMQSeriesMVSSubApp. Although this problem will not break
applications created with versions of VisualAge Smalltalk up to and
including V 6.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)')
The following are changes to IBM Smalltalk Programmer's Reference,
Chapter 13: Secure Sockets Layer. The number items are the page
headings under which the changes should be made. Following *** are
instructions for that section.
1) Overview
*** Replace the last sentence in the second paragraph with...
Although the binaries for the OpenSSL library are provided with
VisualAge Smalltalk, it is recommended that the user download and
compile OpenSSL for their platform to maximize the security of their
applications.
2) SSL Example Workspaces Certificate and Private Key
***Rename the page as "SSL Example - Certificates and Keys"
*** Replace the entire page with the following...
Note: These certificates are for demo use only and should not be used
for production applications.
Server Certificate - copy and paste the following certificate
(including the BEGIN and END lines) into a text file called
vast_server.pem and reference it for the samples.
-----BEGIN CERTIFICATE-----
MIIDPjCCAqegAwIBAgIBATANBgkqhkiG9w0BAQQFADBvMQswCQYDVQQGEwJVUzEX
MBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExEDAOBgNVBAcTB1JhbGVpZ2gxDDAKBgNV
BAoTA0lCTTEMMAoGA1UECxMDU1RHMRkwFwYDVQQDExBJQk0tVkFTVC1UZXN0LUNB
MB4XDTAzMDYyMzE0MTE0MloXDTA0MDYyMjE0MTE0MlowYTELMAkGA1UEBhMCVVMx
FzAVBgNVBAgTDk5vcnRoIENhcm9saW5hMQwwCgYDVQQKEwNJQk0xDDAKBgNVBAsT
A1NURzEdMBsGA1UEAxMUSUJNLVZBU1QtVGVzdC1TZXJ2ZXIwgZ8wDQYJKoZIhvcN
AQEBBQADgY0AMIGJAoGBALaRCPS20sz9F44i4RpUKFnFwZx4g8GWjl4jqqFUFrMd
NfGU2+KySttISYeLPIiGirC12jHGRBuXDxfrC4YY8u7co5FT70PMo42gHGfDU2Ut
aZ9ilSyP44DPz6sgP4HzU5GM9bwil1sudSXg78hs9zTnS5NoBJQrIKNzSMqaI/Av
AgMBAAGjgfcwgfQwCQYDVR0TBAIwADAsBglghkgBhvhCAQ0EHxYdT3BlblNTTCBH
ZW5lcmF0ZWQgQ2VydGlmaWNhdGUwHQYDVR0OBBYEFIDZP9yMyGo80NMaT8wZBAU/
prwkMIGZBgNVHSMEgZEwgY6AFFIb04cA37qQjG60yrJKxkBEgP++oXOkcTBvMQsw
CQYDVQQGEwJVUzEXMBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExEDAOBgNVBAcTB1Jh
bGVpZ2gxDDAKBgNVBAoTA0lCTTEMMAoGA1UECxMDU1RHMRkwFwYDVQQDExBJQk0t
VkFTVC1UZXN0LUNBggEAMA0GCSqGSIb3DQEBBAUAA4GBAIMss/uwGJcmk6xA2jmR
ePQbbUv+/B1HsE/KgITlKMJ7D7/+h560uhLryG3ZkJMCzaAa8QQRuP6sqx4bBm1/
6v7ygXELebqR8vSXDOAc3e31tymfnxmiyPk4sEeWKcuGmVWqQw3ewfSnbhz58BTk
HU7fwzWyIBWJ89QJ3t8lIkUV
-----END CERTIFICATE-----
Server Private Key - copy and paste the following private key
(including the BEGIN and END lines) into a text file called
vast_server_key.pem and reference it for the samples.
-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQC2kQj0ttLM/ReOIuEaVChZxcGceIPBlo5eI6qhVBazHTXxlNvi
skrbSEmHizyIhoqwtdoxxkQblw8X6wuGGPLu3KORU+9DzKONoBxnw1NlLWmfYpUs
j+OAz8+rID+B81ORjPW8IpdbLnUl4O/IbPc050uTaASUKyCjc0jKmiPwLwIDAQAB
AoGBAKketbMr4R8vnTB4MxqWt0JiJTZzlWoxs/SVCa2lHdoSxzPhd8gK7bkwv5ym
aQ73w2ZrL5NIXTNJvhukCurQFcmJfeJIga/PlJcgQJ4NkI1YrZTkcyKEPRFAF9nP
fdHT/P/fcLCzw0pMFf7NglVCWY2WB3XHXQpnaQIp0OZF8xOxAkEA7lOF01FuaApB
N3ksZbjp0GjclcHMMBcqkIwko0deaH3Rb6wDEVj9vrHw1Ls3VKsrJw4cFZyybdW0
b5iChvEt5QJBAMQa8sYMytIFsz5lJr6wEWHdfmMaTo6J4f6OmeEvwskA5aIjnHV5
6feb08kpkPLbbOOQU49rQZWsp6NOP+7cZIMCQQCqLY/Y1kPdHL127BqsxD6JJ+ej
NBAmotQtBTVANj0OphEACbbjE0WVfqA2dzzKQ7N7ntKlCBBM55WBPkiuLNeVAkBO
mSpyvI/R65zyxiHoTbM50UelutZ/hL4Cg+8i9TyRyX1AJhvAbfObXWZd+v3wiIe1
EZScJ/XqYn/yERvIxaa3AkBDPo8lXPpOIJhGVQuBWuUdneG9wYvOSD4igeIeeLt2
YQMff3zboMdz/E3vvwxAZXddTvTKtu3fxxJ6yYbrtaxR
-----END RSA PRIVATE KEY-----
Client Certificate - copy and paste the following certificate
(including the BEGIN and END lines) into a text file called
vast_client.pem and reference it for the samples.
-----BEGIN CERTIFICATE-----
MIIDPjCCAqegAwIBAgIBAjANBgkqhkiG9w0BAQQFADBvMQswCQYDVQQGEwJVUzEX
MBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExEDAOBgNVBAcTB1JhbGVpZ2gxDDAKBgNV
BAoTA0lCTTEMMAoGA1UECxMDU1RHMRkwFwYDVQQDExBJQk0tVkFTVC1UZXN0LUNB
MB4XDTAzMDYyMzE0MTE1MloXDTA0MDYyMjE0MTE1MlowYTELMAkGA1UEBhMCVVMx
FzAVBgNVBAgTDk5vcnRoIENhcm9saW5hMQwwCgYDVQQKEwNJQk0xDDAKBgNVBAsT
A1NURzEdMBsGA1UEAxMUSUJNLVZBU1QtVGVzdC1DbGllbnQwgZ8wDQYJKoZIhvcN
AQEBBQADgY0AMIGJAoGBAOS5fUTL0ONwTnVEVfOnGPf0pO2Cb5kB2oFtvowkHq70
qoCMkgHFa3zX2/x4EiOkwS8BB/YFdRQKD/VIb+V0Eo2TsOmu7FPGFAq+KmMUDBgi
Hl5J0Biro/KRbrtkpADsV8u+MjAcsWN1ytxREVP6hN3OgGRiYxpNdp2jFLfdvBHB
AgMBAAGjgfcwgfQwCQYDVR0TBAIwADAsBglghkgBhvhCAQ0EHxYdT3BlblNTTCBH
ZW5lcmF0ZWQgQ2VydGlmaWNhdGUwHQYDVR0OBBYEFJRtaSXbZ+VqVR1vmpUAd6r2
7pseMIGZBgNVHSMEgZEwgY6AFFIb04cA37qQjG60yrJKxkBEgP++oXOkcTBvMQsw
CQYDVQQGEwJVUzEXMBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExEDAOBgNVBAcTB1Jh
bGVpZ2gxDDAKBgNVBAoTA0lCTTEMMAoGA1UECxMDU1RHMRkwFwYDVQQDExBJQk0t
VkFTVC1UZXN0LUNBggEAMA0GCSqGSIb3DQEBBAUAA4GBAIHRjlq/naUfAKtq9RgF
rQ7dUR4cVCbCEBfXtBEhpkcib0aBh+YguNBknyDa6Gjo+RjR6DeW/GSvOg4wfH4n
tOr2C6yYm5z/zEeqF6/HRSLGPXtlkR8wJeACgJmlYjl1TiYhr7HNfEJ5azHFgMCt
1lukQ3fqke3HQS3g92boCrPD
-----END CERTIFICATE-----
Client Private Key - copy and paste the following private key
(including the BEGIN and END lines) into a text file called
vast_client_key.pem and reference it for the samples.
-----BEGIN RSA PRIVATE KEY-----
MIICXQIBAAKBgQDkuX1Ey9DjcE51RFXzpxj39KTtgm+ZAdqBbb6MJB6u9KqAjJIB
xWt819v8eBIjpMEvAQf2BXUUCg/1SG/ldBKNk7DpruxTxhQKvipjFAwYIh5eSdAY
q6PykW67ZKQA7FfLvjIwHLFjdcrcURFT+oTdzoBkYmMaTXadoxS33bwRwQIDAQAB
AoGBALELZ4zeG1ZB82lQORv+JxSf2R5DzfBo/+MZuNovh1Sz7FrO9KHMV/Rt/kmC
A8B1Ylfo+2mTNdoKI+ogZQT+gPCBWYqmHiOUs4DkH6kvDuS526Uwg3psIJpSUrDw
j9yz+XxU6n3+WePtjk/9Ma7VrKrselqMUMnlXrSDTTLLeM31AkEA8siQkAaQR5u8
1OzSuFQYYdDR/M3fkdLpbdRvrvi/Psp1Ni9F5Zo+sBb3MWpxr7znB5YCl2pKb6kP
G25ZrHkjiwJBAPEs/+qyyUSXkvP92zaaFwgWH3lRZY6I/ukMi6GkBhC7ye5No0Nm
MxJTjlkL6HzA2HKArKiAzpV1nk4SVzmYWWMCQQCMSWJnJrPF/PKfIn0cb9Nq6gv8
hUVzcKjbgs5KD4gKk1gpSCWeZ4NjotGRZ01r276vfnne3ldGsCx/kEMWyyTDAkBx
SADA/c9Z35RP9LpF0GTnEHUiJ+B67dBGKPVhLEkJDRvRSjhYjSWKAyNGojhGeNJy
Hgx7bV0biM6dvzGnRO8fAkA3TOUH5vgm2T4DzntdgNYCn2TBdzM44IW2z9xTvuoG
V2I4P8Gmr8XWrrjdU0s2+J6SuqmOCijKVdFU3c/1oquW
-----END RSA PRIVATE KEY-----
Certificate Authority File - copy and paste the following CA
certificate (including the BEGIN and END lines) into a text file called
vast_ca.pem and reference it for the samples.
-----BEGIN CERTIFICATE-----
MIIDITCCAoqgAwIBAgIBADANBgkqhkiG9w0BAQQFADBvMQswCQYDVQQGEwJVUzEX
MBUGA1UECBMOTm9ydGggQ2Fyb2xpbmExEDAOBgNVBAcTB1JhbGVpZ2gxDDAKBgNV
BAoTA0lCTTEMMAoGA1UECxMDU1RHMRkwFwYDVQQDExBJQk0tVkFTVC1UZXN0LUNB
MB4XDTAzMDYyMzE0MTE0MVoXDTA0MDYyMjE0MTE0MVowbzELMAkGA1UEBhMCVVMx
FzAVBgNVBAgTDk5vcnRoIENhcm9saW5hMRAwDgYDVQQHEwdSYWxlaWdoMQwwCgYD
VQQKEwNJQk0xDDAKBgNVBAsTA1NURzEZMBcGA1UEAxMQSUJNLVZBU1QtVGVzdC1D
QTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAvA0FiByHnmVlQDCsfOaIp79J
Qg3pEARsiYipj1mEYBwx9qYdo655JX72DYVYjPyzh5MWOQFyu9u7f6JI8mTlw4p7
QX9oUiHMihs/oyPDYZA8Zih7NcQOBwUcBKdZ4pAkUJKKkd9bb3SdMU4DnX11Ym94
sT1YvxsNKYVwKN9Cb98CAwEAAaOBzDCByTAdBgNVHQ4EFgQUUhvThwDfupCMbrTK
skrGQESA/74wgZkGA1UdIwSBkTCBjoAUUhvThwDfupCMbrTKskrGQESA/76hc6Rx
MG8xCzAJBgNVBAYTAlVTMRcwFQYDVQQIEw5Ob3J0aCBDYXJvbGluYTEQMA4GA1UE
BxMHUmFsZWlnaDEMMAoGA1UEChMDSUJNMQwwCgYDVQQLEwNTVEcxGTAXBgNVBAMT
EElCTS1WQVNULVRlc3QtQ0GCAQAwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQQF
AAOBgQBITpyXpjcqy9T12ziqZx20MUmNf8bJNqbFyO/ARlUslXxbUuJK7HRrCAyi
M/gwJTeWa/Y3f93CV4nKw/CCfmfqXd+oyzGLZzmcvvYP3bWlLPBNBff4mzjsj8TG
81hyH2T5XJ3Z3FemtCFCgiU9egPnhTLqZlMz0N3gX3BefOIQSg==
-----END CERTIFICATE-----
3) SSL Server Workspace
***Replace the entire page with the following
"Make sure that vast_server.pem and vast_server_key.pem are in a
directory of your choice
and referenced in <dir>. The following example uses Unix style path
separators."
[ | config anSciSocketAddress listenSocket secureSocket rv msg |
config := SciSslSocketConfiguration new
certificateFilename: '<dir>/vast_server.pem';
privateKeyFilename: '<dir>/vast_server_key.pem';
sslVersion: SciSslConstants::SSLv3;
yourself.
anSciSocketAddress := (SciSocketAddress new)
address: SciSocketConstants::INADDRANY;
port: 4433.
listenSocket := SciSslSocket newStreamSocket.
(rv := listenSocket bind: anSciSocketAddress) isSciError
ifTrue: [ self halt ].
(rv := listenSocket listen: 5) isSciError ifTrue: [ self halt ].
(secureSocket := listenSocket accept) isSciError ifTrue: [ self halt ].
listenSocket close.
(rv := secureSocket sslInitialize: config) isSslError
ifTrue: [ secureSocket close. self halt ].
(rv := secureSocket sslAccept) isSslError
ifTrue: [ secureSocket close. self halt ].
msg := ByteArray new: 4096.
(rv := secureSocket recv: msg length: 4096 startingAt: 1 flags: 0)
isSslError ifTrue: [ self halt ].
Transcript cr; nextPutAll: 'SslServer Got: ', msg asString.
rv := secureSocket
send: 'I hear you.' abrAsPSZ
length: 11
startingAt: 1
flags: 0.
rv isSslError ifTrue: [ self halt ].
secureSocket close. ] fork
4) SSL Client Workspace
***Replace the entire page with the following...
"Make sure that vast_client.pem, vast_client_key.pem and vast_ca.pem
are in a directory of your choice and referenced in <dir>. The
following example uses Unix style path separators. This client code
performs a verification of the server certificate."
[ | config rv anSciSocketAddress secureSocket msg |
config := SciSslSocketConfiguration new
certificateFilename: '<dir>/vast_client.pem';
privateKeyFilename: '<dir>/vast_client_key.pem';
caFile: '<dir>/vast_ca.pem';
sslVersion: SciSslConstants::SSLv3;
verify: SciSslConstants::SSL_VERIFY_PEER
| SciSslConstants::SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
verifyDepth: 1;
yourself.
anSciSocketAddress :=
(SciSocketAddress fromString: '127.0.0.1' )
family: SciSocketConstants::AFINET;
port: 4433.
secureSocket := SciSslSocket newStreamSocket.
(rv := secureSocket connect: anSciSocketAddress) isSciError
ifTrue: [ secureSocket close. self halt ].
(rv := secureSocket sslInitialize: config) isSslError
ifTrue: [ secureSocket close. self halt ].
(rv := secureSocket sslConnect) isSslError
ifTrue: [ secureSocket close. self halt ].
rv := secureSocket
send: 'Hello World!' abrAsPSZ
length: 12
startingAt: 1
flags: 0.
rv isSslError ifTrue: [ self halt ].
msg := ByteArray new: 4096.
(rv := secureSocket recv: msg length: 4096 startingAt: 1 flags: 0)
isSslError ifTrue: [ self halt ].
Transcript cr; nextPutAll: 'SslClient Got -> ', msg asString trimNull,
' <- '.
secureSocket close. ] fork.
5) Application Programming Interface
***Change third paragraph to...
The binaries for the OpenSSL library are provided with VisualAge
Smalltalk.
However, it is recommended that the user download and compile the
latest
version of OpenSSL to maximize the security of SSL applications.
Source and documentation can be found at the OpenSSL Website:
http://www.openssl.org
6) Supported SciSslSocket functions
*** Change list to...
close
getSession
isSecure
setSession:
sslAccept
sslBytesAvailableToRead
sslConnect
sslGetPeerCertificate
sslInitialize:
sslSetVerify:
sslSetVerifyDepth:
sslVerifyCertificate
7) SciSslSocket protocols - Instance Methods
*** Add the following entries to pre-existing ones...
sslGetPeerCertificate
returns a pointer to the peer's certificate, if presented, or nil if
not presented.
Due to the protocol definition, a TLS/SSL server will always send a
certificate, if present. A client will only send a certificate when
explicitly requested to do so by the server. If an anonymous cipher
is used, no certificates are sent. This method is useful for
extracting details of the certificate.
sslSetVerify: verifyMode
Set the verification mode for the SSL connection. Valid modes of
operation are...
SSL_VERIFY_NONE -
Server - the server will not send a client certificate request to
the client, so the client will not send a certificate.
Client - if anonymous ciphers are not in use (by default
disabled), the server will send a certificate which will be
checked.
The result of the certificate verification process can be checked
after the TLS/SSL handshake using the sslVerifyCertificate
method. The handshake will be continued regardless of the
verification result.
SSL_VERIFY_PEER -
Server - the server sends a client certificate request to the
client. The certificate returned (if any) is checked. If the
verification process fails, the TLS/SSL handshake is immediately
terminated with an alert message containing the reason for the
verification failure. The behavior can be controlled by or-ing
the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT and
SSL_VERIFY_CLIENT_ONCE flags.
Client - the server certificate is verified. If the verification
process fails, the TLS/SSL handshake is immediately terminated
with an alert message containing the reason for the verification
failure. If no server certificate is sent, because an anonymous
cipher is used, SSL_VERIFY_PEER is ignored.
SSL_VERIFY_FAIL_IF_NO_PEER_CERT -
Server - if the client did not return a certificate, the TLS/SSL
handshake is immediately terminated with a handshake failure
alert. This flag must be used together with SSL_VERIFY_PEER.
Client - ignored
SSL_VERIFY_CLIENT_ONCE -
Server - only request a client certificate on the initial TLS/SSL
handshake. Do not ask for a client certificate again in case of a
renegotiation. This flag must be used together with
SSL_VERIFY_PEER.
Client - ignored
Note: Exactly one of the mode flags SSL_VERIFY_NONE and
SSL_VERIFY_PEER must be set at any time. Verification failure will
lead to a termination of the TLS/SSL handshake with an alert message,
if SSL_VERIFY_PEER is set.
sslSetVerifyDepth:
Set the maximum depth to which the certificate chain will be
verified. This depth is only used if SSL_set_verify has previously
been set to SSL_VERIFY_PEER
sslVerifyCertificate
Answers the result of peer certificate verification.
If verification mode is not set to SSL_VERIFY_NONE (see
sslSetVerify:), sslVerifyCertificate checks the validity of the
peer's X509 certificate to the specified verify depth, or 1 level if
unspecified. Although there are many ways the verification of a
certificate can fail (expired, revoked, invalid, etc.), the only
error code that is returned is the last error that occurred during
processing.
8) SciSslContext protocols - Instance Methods
*** Replace page with the following...
certificateChainFile: aCertificateChainFilename
The certificate must be in PEM format and must be sorted starting
with the subject's certificate (actual client or server certificate),
followed by intermediate CA certificates if applicable, and ending at
the highest level (root) CA.
certificateFile: anX509CertificateFilename
Sets the context's certificate to be anX509CertificateFilename. The
file must be in PEM format.
privateKey: anSslPrivateKey
Sets the privateKey used by this context to encrypt and decrypt data
flowing over the SSL/TLS connection.
sslMethod
Answers the SSL method being used by this context. The SSL method
describes the protocol version being used by the peer using this
context.
sslMethod: anSslMethod
Sets the SSL method being used for this connection to be the method
specified by aPlatformFunction.
SSLV2 - SSL version 2
SSLV3 - SSL version 3
SSLV23 - SSL version 2 or 3
TLSV1 - TLS version 1 (sometimes called 3.1).
9) SciSslSocketConfiguration protocols - Instance methods
*** Add the following entries to pre-existing ones...
caFile: aCertificateAuthorityFile
Sets the CA file for the configuration. The Certificate Authority
(CA) file is a trusted certificate used for verification purposes.
caFile
Answers the CA file for the configuration.
caPath: aCAPath
Sets the path to the directory containing CA certificate files.
caPath
Answers the path to the directory containing CA certificate files
certificateChainFilename: aPemCertificateChainFilename
Sets the certificate chain file to be used by the configuration for
verification.
certificateChainFilename
Answers the certificate chain file being used by the configuration
for verification.
verify: verifyMode
Set the verification mode for the SSL configuration. Valid modes of
operation are...
SSL_VERIFY_NONE -
Server - the server will not send a client certificate request to
the client, so the client will not send a certificate.
Client - if anonymous ciphers are not in use (by default
disabled), the server will send a certificate which will be
checked. The result of the certificate verification process can
be checked after the TLS/SSL handshake using the
sslVerifyCertificate method. The handshake will be continued
regardless of the verification result.
SSL_VERIFY_PEER -
Server - the server sends a client certificate request to the
client. The certificate returned (if any) is checked. If the
verification process fails, the TLS/SSL handshake is immediately
terminated with an alert message containing the reason for the
verification failure. The behavior can be controlled by or-ing
the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT and
SSL_VERIFY_CLIENT_ONCE flags.
Client - the server certificate is verified. If the verification
process fails, the TLS/SSL handshake is immediately terminated
with an alert message containing the reason for the verification
failure. If no server certificate is sent, because an anonymous
cipher is used, SSL_VERIFY_PEER is ignored.
SSL_VERIFY_FAIL_IF_NO_PEER_CERT -
Server - if the client did not return a certificate, the TLS/SSL
handshake is immediately terminated with a handshake failure
alert. This flag must be used together with SSL_VERIFY_PEER.
Client - ignored
SSL_VERIFY_CLIENT_ONCE -
Server - only request a client certificate on the initial TLS/SSL
handshake. Do not ask for a client certificate again in case of a
renegotiation. This flag must be used together with
SSL_VERIFY_PEER.
Client - ignored
Note: Exactly one of the mode flags SSL_VERIFY_NONE and
SSL_VERIFY_PEER must be set at any time. Verification failure will
lead to a termination of the TLS/SSL handshake with an alert message,
if SSL_VERIFY_PEER is set.
verify
Answer the verification mode for the SSL configuration.
verifyDepth: anInteger
Set the maximum depth to which the certificate chain will be verified
to anInteger. This depth is only used if #verify: has previously
been set to include SSL_VERIFY_PEER.
verifyDepth
Answer the maximum depth to which the certificate chain will be
verified
10) SciSslError protocols
*** Replace paragraph with the following...
SciSslError is an error object subclassed from SciError. When a call to
the underlying OpenSSL API fails, an instance of SciSslError is
returned which can then be inspected to figure out the cause of the
failure. Every attempt is made to provide helpful error information,
if possible.
11) SciSslBlockingDispatcher protocols
*** Replace paragraph with the following...
VisualAge Smalltalk uses a singleton instance of
SciSslBlockingDispatcher to perform function calls to the underlying
OpenSSL API calls on behalf of the SciSslSocketInterface classes.
Directly accessing this singleton is not necessary but is mentioned
here for completeness.
The following are changes to IBM Smalltalk Programmer's Reference,
Chapter 12: Socket Communications. The number items are the page
headings under which the changes should be made. Following *** are
instructions for that section.
1) SciSocketManager Protocols
*** Under Instance Methods add the following as the last entry ...
ping: port at: hostname
Answers a string representation of the SciSocketAddress of the pinged
host or an error string.
port:
The port number at which to ping the host
hostname:
The name of the host to ping.
The ping:at: operation is a TCP ping utility. It can also be invoked
via the String>>sciPing method as in the following example...
'www.ibm.com:80' sciPing
There are several additons to SSL support for peer X509 certificate
verification on the SciSslsocket and SciSslSocketConfiguration levels.
The information in this README item is meant to complement the Secure
Sockets Layer chapter of the Smalltalk Programmer's Reference. An
example SciSslSocketConfiguration using this new verfication API
appears at the end of this README.
SciSslSocket protocols - Instance Methods
sslGetPeerCertificate
Returns a pointer to the X509 certificate the peer presented or
an SslError. If the peer did
not present a certificate, nil is returned.
Due to the protocol definition, a TLS/SSL server will always
send a certificate, if present. A client will only send a
certificate when explicitly requested to do so by the server.
If an anonymous cipher is used, no certificates are sent.
sslSetVerify: verifyMode
Set the verification mode for the SSL connection. Valid modes
of operation are...
SSL_VERIFY_NONE -
Server - the server will not send a client certificate
request to the client, so the client will not send a
certificate.
Client - if anonymous ciphers are not in use (by default
disabled), the server will send a certificate which will
be checked.
The result of the certificate verification process
can be checked after the TLS/SSL handshake using
the sslVerifyCertificate method. The handshake will
be continued regardless of the verification result.
SSL_VERIFY_PEER -
Server - the server sends a client certificate request to
the client. The certificate returned (if any) is checked.
If the verification process fails, the TLS/SSL handshake is
immediately terminated with an alert message containing the
reason for the verification failure. The behaviour can be
controlled by or-ing the additional
SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE
flags.
Client - the server certificate is verified. If the
verification process fails, the TLS/SSL handshake is
immediately terminated with an alert message containing the
reason for the verification failure. If no server
certificate is sent, because an anonymous cipher is used,
SSL_VERIFY_PEER is ignored.
SSL_VERIFY_FAIL_IF_NO_PEER_CERT -
Server - if the client did not return a certificate, the
TLS/SSL handshake is immediately terminated with a
handshake failure alert. This flag must be used together
with SSL_VERIFY_PEER.
Client - ignored
SSL_VERIFY_CLIENT_ONCE -
Server - only request a client certificate on the initial
TLS/SSL handshake. Do not ask for a client certificate
again in case of a renegotiation. This flag must be used
together with SSL_VERIFY_PEER.
Client - ignored
Note: Exactly one of the mode flags SSL_VERIFY_NONE and
SSL_VERIFY_PEER must be set at any time. Verification failure
will lead to a termination of the TLS/SSL handshake with an
alert message, if SSL_VERIFY_PEER is set.
sslSetVerifyDepth:
Set the maximum depth to which the certificate chain will be
verified. This depth is only used if SSL_set_verify has
previously been set to SSL_VERIFY_PEER.
sslVerifyCertificate
Answers the result of peer certificate verification.
If verification mode is not set to SSL_VERIFY_NONE (see
sslSetVerify:), sslVerifyCertificate checks the validity of the
peer's X509 certificate to the specified verify depth, or 1
level if unspecified. Although there are many ways the
verification of a certificate can fail (expired, revoked,
invalid, etc.), the only error code that is returned is the
last error that occurred during processing.
SciSslContext protocols - Instance Methods
certificateChainFile: aCertificateChainFilename
The certificate must be in PEM format and must be sorted
starting with the subject's certificate (actual client or
server certificate), followed by intermediate CA certificates
if applicable, and ending at the highest level (root) CA.
certificateFile: anX509CertificateFilename
Sets the context's certificate to be anX509CertificateFilename.
The file must be in PEM format.
privateKey: anSslPrivateKey
Sets the privateKey used by this context to encrypt and decrypt
data flowing over the SSL/TLS connection.
sslMethod
Answers the SSL method being used by this context. The SSL
method describes the protocol version being used by the peer
using this context.
sslMethod: anSslMethod
Sets the SSL method being used for this connection to be the
method specified by aPlatformFunction.
SSLV2 - SSL version 2
SSLV3 - SSL version 3
SSLV23 - SSL version 2 or 3
TLSV1 - TLS version 1 (sometimes called 3.1).
SciSslSocketConfiguration protocols - Instance methods
caFile: aCertificateAuthorityFile
Sets the CA file for the configuration. The Certificate
Authority (CA) file is a trusted certifcate used for
verification purposes.
caFile
Answers the CA file for the configuration.
caPath: aCAPath
Sets the path to the directory containing CA certificate files.
caPath
Answers the path to the directory containing CA certificate
files
certificateChainFilename: aPemCertificateChainFilename
Sets the certificate chain file to be used by the configuration
for verification.
certificateChainFilename
Answers the certificate chain file beign used by the
configuration for verification.
verify: verifyMode
Set the verification mode for the SSL configuration. Valid
modes of operation are...
SSL_VERIFY_NONE -
Server - the server will not send a client certificate
request to the client, so the client will not send a
certificate.
Client - if anonymous ciphers are not in use (by default
disabled), the server will send a certificate which will be
checked. The result of the certificate verification process
can be checked after the TLS/SSL handshake using the
sslVerifyCertificate method. The handshake will be
continued regardless of the verification result.
SSL_VERIFY_PEER -
Server - the server sends a client certificate request to
the client. The certificate returned (if any) is checked.
If the verification process fails, the TLS/SSL handshake is
immediately terminated with an alert message containing the
reason for the verification failure. The behaviour can be
controlled by or-ing the additional
SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE
flags.
Client - the server certificate is verified. If the
verification process fails, the TLS/SSL handshake is
immediately terminated with an alert message containing the
reason for the verification failure. If no server
certificate is sent, because an anonymous cipher is used,
SSL_VERIFY_PEER is ignored.
SSL_VERIFY_FAIL_IF_NO_PEER_CERT -
Server - if the client did not return a certificate, the
TLS/SSL handshake is immediately terminated with a
handshake failure alert. This flag must be used together
with SSL_VERIFY_PEER.
Client - ignored
SSL_VERIFY_CLIENT_ONCE -
Server - only request a client certificate on the initial
TLS/SSL handshake. Do not ask for a client certificate
again in case of a renegotiation. This flag must be used
together with SSL_VERIFY_PEER.
Client - ignored
Note: Exactly one of the mode flags SSL_VERIFY_NONE and
SSL_VERIFY_PEER must be set at any time. Set the verification
mode for the SSL connection. Valid modes of operation are...
verify
Answer the verification mode for the SSL configuration.
verifyDepth: anInteger
Set the maximum depth to which the certificate chain will be
verified to anInteger. This depth is only used if #verify: has
previously been set to include SSL_VERIFY_PEER.
verifyDepth
Answer the maximum depth to which the certificate chain will be
verified
The following is an example SciSslSocketConfiguration using the new API
to enable peer certificate verification...
SciSslSocketConfiguration new
certificateFilename: '<path>/certificateFilename.pem';
privateKeyFilename: '<path>/privateKeyFilename.pem';
caFile: '<path>/caFilename.pem';
sslVersion: SciSslConstants::SSLv3;
verify: SciSslConstants::SSL_VERIFY_PEER |
SciSslConstants::SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
verifyDepth: 1;
yourself.
To help with debugging problems when using the TCP/IP communication protocol, a tracing capability at the socket API level for the platform Smalltalk is running on has been added. The following show how to turn on and off the trace from Smalltalk. " Turn on TCP/IP API Trace " SciSocketManager default traceStart. " Turn on TCP/IP API Trace plus a trace of the first 256 bytes of data for a Send and Receive " SciSocketManager default traceStartAtLevel: 2. " Set the name of the TCP/IP trace file. The Default is 'sciTrace.log'. " SciSocketManager default traceFilename: 'MyTrace.log'. " Turn off TCP/IP Trace " SciSocketManager default traceEnd.
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.
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.
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
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
Prior to this fix, the only provided method for changing the Oracle initialization mode was to create a subclass of AbtOracle8DatabaseManager in order to override the #userDefinedInitializeMode method. While this method is still available, it is now possible to change the default initialization mode by setting a class variable. The provided method for doing this is AbtOracle8DatabaseManager class>>#defaultInitializeMode: . The shipped default value is OCI_DEFAULT, which is unchanged from previous VisualAge Smalltalk version. See the comment in AbtOracle8DatabaseManager class>>#defaultInitializeMode: for other possible values.
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.
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
If you are running DB2 through IBM's ODBC layer and you are not using any other ODBC at the same time in the same image, you can execute the following line of code to force the VisualAge Smalltalk ODBC layer to use the AbtIbmCliBigIntField datatype for BigInt fields: AbtOdbcDatabaseManager typeDict at: -5 put: AbtIbmCliBigIntField.
VisualAge Smalltalk Enterprise V4.5 was the last release to ship with ODBC drivers. The drivers in V4.5 were provided by MERANT (formerly INTERSOLV Inc.). If you need to obtain ODBC drivers, the DataDirect product may still available directly from MERANT. You can also check your Database Resource Manager for ODBC drivers. Most, if not all, major Database Resource Managers now ship with ODBC drivers.
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.
To ensure all information is displayed on your computer, we encourage you to use the highest resolution offered by your display terminal.
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.
DBCS cookies are not supported using the Servlet Interface. This is a limitation of the HTTP Server.
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
The webpage for the Windows Resource Hacker utility has moved. In the IBM Smalltalk User's Guide, Changing the icon on Windows and OS/2, change the link behind the Windows ResHacker item to http://www.angusj.com/resourcehacker/
The VisualAge Smalltalk Domino Connection feature is now supported on Windows XP when running with Lotus Notes V6.0.
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 <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>
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.
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 Windows Server 2003 Red Hat Linux 9 Red Hat Enterprise Linux 2.1 AIX 5.2 Solaris 8.0 and 9.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.
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.0.1) -- 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.
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.
On an AIX machine, before installing Smalltalk for the first time, use Smitty or Smit to create a Journalled File System.
On an AIX machine, before installing base Smalltalk for the first time, use Smitty or Smit to increase the disk size to 200 Megabytes.
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.
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.
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.
The packager algorithm for locating IC snapshot files and generating
output image files has unobvious dependencies on the ini file property
"packagingRootDirectory". Here are additions for part 7 of the IBM
Smalltalk User's Guide:
-rht
Chapter 34. Advanced Packaging
...
Detailed Packaging Procedure
...
Add a bullet to the list between currnt bullets 3 and 4:
3.5. ... specify a new file name in the Output File field.
Note: The packager interprets the specified output file path as
follows. If the path is a simple filename, then the output file will be
written to the CFS #startUpDirectory. If the path is a relative path,
including a relative specification for the output file parent
directory, then the specified output file path is interpreted as
relative to the value of the "ini" file property
"packagingRootDirectory". If, otherwise, the path is an absolute path,
it is used as is. When running on UNIX, you may find it convenient to
modify the default specification for "packagingRootDirectory" to
indicate a writable subdirectory of your #startUpDirectory. For example:
packagingRootDirectory=./pkging
Chapter 36. Packaging with image components
...
Step-by-step examples building VisualAge ICs
...
Creating a leaf IC
...
Replace the 2nd paragraph of bullet 7 with:
7.5. ... Change the name of the output file to ictest.ic.
Note: Refer to Chapter 34 for information on the interpretation of
directory path information provided with your output file path
specification.
Chapter 36. Packaging with image components
...
Troubleshooting
...
Problems during packaging
...
Add a new problem solution:
Prerequisite ICs.
During reduction, the packager interrogates the snapshot files
associated with the prerequisite ICs you selected. It expects to find
these snapshot files under the root of the filesystem directory tree
specified by the "ini" file property "packagingRootDirectory". If you
want to customize the "packagingRootDirectory" property, then you must
ensure that you copy the required snapshot files to this alternate
location. On UNIX, it is sufficient to create a symbolic link (under
your specified packaging root) to the directory containing the snapshot
files you need.
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).
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.
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.
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.
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.
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.
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.
The RMI in Server Smalltalk will run under JDK 1.3, using the same techniques that were required for JDK 1.2.
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.
An SST HTTP server now writes an "access" log, named "httpd.log". Entries in the log are formatted according to the default format used by the Apache HTTP server, in order to enable tooling for Apache logs to be used for SST logs as well. This access log is initialized in SstHttpServer>>startUp. An alternate formatter or message target can be specified by sending #accessLog: prior to #startUp.
The SST HTTP client support for HTTP proxies has been enhanced to
provide for tunneling HTTPS through an HTTP proxy.
The central feature of this enhancement is a new connection class -
SstHttpsTunnelConnection - which knows how to do the upgrade from TCP
to SSL.
To make use of this enhancement, a client must use a transport
configuration that specifies a #socketClass of SciSocket and a
#connectionClass of SstHttpTunneledConnection. The following method has
been added as a convenience for defining a transport configuration to
support this scenario.
SstHttpClient class>>
#initializeTransportScheme:forHttpsTunnelThrough:proxyAuth:
Example:
SstHttpClient
initializeTransportScheme: 'local_https_tunnel'
forHttpsTunnelThrough: 'proxy.acme.com:80'
proxyAuth: nil
The method above accepts 'nil' as a proxyAuth credential to indicate
that proxy authentication is not required.
The class SstHttpClient is introduced with this enhancement. A client
using the transport configuration defined above would be created using
the factory method SstHttpClient class>>#forTransportScheme:, as in the
example below.
|client|
(client := SstHttpClient forTransportScheme: 'local_https_tunnel')
startUp.
[client get: 'https://www.foobar.com/secure/index.html']
ensure: [client shutDown].
It is also possible to configure SST so that the convenience method
SstHttpUrl>>fetch uses this tunneling feature. This is done in the same
way as illustrated above for an application-specific transport
configuration, specifying instead the identifer for the default https
client configuration.
SstHttpClient
initializeTransportScheme: 'httpsl'
forHttpsTunnelThrough: 'proxy.acme.com:80'
proxyAuth: nil
Having done this, the following code is equivalent to the example above.
'https://www.foobar.com/secure/index.html' sstAsUrl fetch
Typically, security policies indicate that an HTTPS client should
validate the X509 certificate presented by an HTTPS server, and should
verify that the identity asserted by a validated certificate is in fact
the identity of the intended server.
Version 6.0.2 includes enhancements to the SST HTTPS client which
enable applications to specify via the security configuration for an
HTTPS client transport that a strict certificate validation policy
should be applied. In addition, an SstHttpClient can be configured with
a @requiredPeerName that will result in the client auto-verifying the
identity asserted by the server credential.
To enable strict certificate validation, the HTTPS client transport
security configuration must specify:
1) @caFile - the file name of a trusted certificate authority (CA)
certificate store, and
2) @verify - the validation policy, and
3) @verifyDepth - the maximum depth of the presented certificate
chain.
The @verify parameter must be set to
"SSL_VERIFY_PEER|SSL_VERIFY_FAIL_IF_NO_PEER_CERT".
Unless known to be too limiting, a reasonable default value for
@verifyDepth is the Integer '2'.
The @caFile is a certificate store in PEM format, as per OpenSSL.
Example 1. The code below configures the default HTTPS client transport
for strict server certificate validation.
(SstTransport configurationRegistry at: 'httpsl')
securityConfiguration: (SciSslSocketConfiguration new
sslVersion: SciSslConstants::SSLv3;
caFile: 'certs/sst_ca.pem';
verify: SciSslConstants::SSL_VERIFY_PEER
| SciSslConstants::SSL_VERIFY_FAIL_IF_NO_PEER_CERT;
verifyDepth: 2;
yourself).
With this configuration in place, the fetch below will fall into the
exception handler if the presented server certificate cannot be
validated against the trusted CA certificate store.
['https://www.acme.com/secure/index.html' sstAsUrl fetch]
when: SstConstants::ExSstNonFatalError
do: [:sig| sig exitWith: ('SSL handshake failed:*'
match: sig arguments last errorObject)].
To enable server identity verification, in addition to certificate
validation, SstHttpsConnection now has a "getter" for @peerCredential,
allowing an application to test the Subject attribute of the server's
X509 certificate. Auto-verification is enabled in SstHttpClient via a
new @requiredPeerName attribute. If this attribute is set, the client
will test the certificate Subject immediately after successful SSL
connection negotiation (prior to sending the HTTP request) and generate
an exception if the Subject does not match the specified
@requiredPeerName.
Example 2.
|client response|
(client := SstHttpClient forTransportScheme: 'httpsl') startUp.
client requiredPeerName: '/who/do'.
[ ['https://www.acme.com/secure/index.html' sstAsUrl fetch]
ensure: [client shutDown]
]
when: SstConstants::ExSstNonFatalError
do: [:sig| sig exitWith: ('Invalid peer:*'
match: sig arguments last errorObject)].
SstUnixSocketDemultiplexer>>sstWarn: sends #abtPadWith:upToLength:onRight:, which is implemented in AbtCLDTAdditions - an app not in the prereq chain of the controller for SstUnixSocketDemultiplexer>>sstWarn:. This method will likely be removed during packaging, causing a runtime DNU. Workaround: include AbtCLDTAdditions when packaging an SST app.
The following information is for the Smalltalk application
programmer.
VisualAge Smalltalk Server for OS/390 and z/OS applications
are created using the VisualAge Smalltalk Enterprise
cross-development environment. To enable a Smalltalk
application running on OS/390 or z/OS to use the dynamic
translation code cache support, also known as the just-in-time
compiler (JIT), the application programmer must use the
development environment to package the Smalltalk application
with the 'Package for LPA' Dumper policy option turned off.
This option is located on the Policies tab of the Packager
Control Panel.
Note: Turning off the 'Package for LPA' dumper policy option
does not preclude a Smalltalk application from running in the
LPA.
The following documentation changes have been made:
VisualAge Smalltalk Server for z/OS and OS/390
Server Guide
Bullet 4 has changed in the section titled
"Step 5: Producing the packaged single image";
4. Select the Startup Code tab from the top of the window. To
specify a startup class, select one from the Image Startup
Class drop-down list. To specify the launch code for the
application, type it into the Application Entry Point input
area. To specify the file name for the packaged image,
type it into the Output File input area. You can also
select Choose to open a file selection window.
Note that when you complete the Modify Instructions step,
the yellow flag is removed from the upper right corner of
the procedure step at the bottom of the window.
To enable the packaged image to use the dynamic
translation code cache support select the Policies tab from
the top of the packager window. Change the Policy Type to
'Dumper' and de-select the 'Package for LPA' option. To
control the dynamic translation code cache size at
execution time see the virtual machine option -mcXXXX in
the 'IBM Smalltalk User's Guide'.
Bullet 4 has changed in the section titled
"Step 5: Producing the packaged base or reusable image";
4. Select the Startup Code tab from the top of the window.
Select a startup class from the Image Startup Class
drop-down list. There is no launch code to specify
for a base image, so you cannot enter a value in the
Application Entry Point input area. To specify the
file name for the packaged image, enter it into the Output
File input area. You can also select Choose to open a file
selection window. Note that when complete the Modify
Instructions step, the yellow flag is removed from the
upper right corner of the procedure step at the
bottom of the window.
To enable the packaged image to use the dynamic
translation code cache support select the Policies tab from
the top of the packager window. Change the Policy Type to
'Dumper' and de-select the 'Package for LPA' option. To
control the dynamic translation code cache size at
execution time see the virtual machine option -mcXXXX in
the 'IBM Smalltalk User's Guide'.
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.
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 AbtWebServerInterfaceBase
App>>AbtWsiConnection>>#handleTransaction: method, change the ExAll
exception reference to ExError.
2. In the AbtWebServerInterfaceBase
App>>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.
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.
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.
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 ]
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: [ ].
Several new runtime files are required by the VAST Web services feature
for 6.0.2. They are:
sstaxis.xsd - An XML schema that contains definitions for common
Java types including 'Map', 'Hashtable', and 'Vector'
sstaxis.map - An XML mapping specification that enables seamless
mapping of common Java types into Smalltalk objects.
abtvast.map -- Contains unique mappings to enable unambiguous
serialization of objects that can be mapped to a variety of schema
types.
The Web services examples have been augmented to demonstrate new Web services functionality (WS-I Basic Profile. SOAP 1.2, security enhancements). The directory structure for the samples has been modified. See the file ./samples/sstws/Readme.txt for additional information about using the Web services samples.
The targetNamespace for the implementation WSDL of the insurance
example was changed from
http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface
to
http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-impl
(added the '-impl' suffix).
The documenation still references the old namespace in some of the code
samples; however, the code samples in the .\samples\sstws directory are
correct.
-------------------------------
How can I override the default XML serialization logic?
XML serialization is performed by objects called 'serializers'.
Developers can supply custom serializers that replace the default
serialization logic.
| container config |
container := SstWSContainer containerNamed: 'MyContainer'.
config := container serializationManager
serializationConfigurationNamed:
SstSoapConstants::SstSoapDefaultEnvelopeNamespace.
config serializer: MyCustomSerializer current.
Alternatively, the serialization configuration itself can be replaced.
| container |
container := SstWSContainer containerNamed: 'MyContainer'.
container serializationManager
addSerializationConfiguration: AbtXmlSerializationConfiguration
newSoapConfiguration
named: SstSoapConstants::SstSoapDefaultEnvelopeNamespace.
-------------------------------
How can I disable/enable SOAP multi-ref serialization?
By default, SOAP encoded messages are constructed using the serialized
named SstSoapOutputSerializer. This serializer causes all complex SOAP
messages to be encoded as SOAP multi-refs. Notice that the
serialization configuration is referenced using the SOAP encoding
namespace.
| container config |
container := SstWSContainer containerNamed: 'MyContainer'.
config := container serializationManager
serializationConfigurationNamed:
SstSoapConstants::SstSoapDefaultEncodingNamespace.
config serializer: AbtXmlSchemaOutputSerializer current.
-------------------------------
How can I supply custom deserializers to provide custom logic for
mapping XML into objects?
Mapping parsed XML into Smalltalk model objects is performed by objects
called 'deserializers'. Developers can supply custom deserializers to
enhance default mapping behavior. Custom deserializers can be created
and set in deserialization configurations.
| container config |
container := SstWSContainer containerNamed: 'MyContainer'.
config := container serializationManager
deserializationConfigurationNamed:
SstSoapConstants::SstSoapDefaultEnvelopeNamespace.
config deserializer: AbtXmlSchemaInputDeserializer current.
Alternatively, the default SOAP deserialization configuration can be
replaced
as shown below.
| container config |
container := SstWSContainer containerNamed: 'MyContainer'.
config := AbtXmlDeserializationConfiguration newSoapConfiguration.
config deserializer: AbtXmlSchemaInputDeserializer current.
container serializationManager
addDeserializationConfiguration: config
named: SstSoapConstants::SstSoapDefaultEnvelopeNamespace.
-------------------------------
How can I print incoming and outgoing SOAP messages on my Web services
server?
The message handler chain can be modified to add code that dumps the
contents of the SOAP message and response.
| factory pluggableHandler |
factory := ( SstWSContainer containerNamed:
'VastSampleServerContainer' ) handlerFactory.
pluggableHandler :=SstWSPluggableHandler new
invokeBlock: [ :anSstWSMessageContext | | message |
[
message := anSstWSMessageContext
propertyNamed: ##wsTransportMessageRequest.
AbtXmlUtility logError: 'Request->'.
AbtXmlUtility logError: message header debugPrintString.
AbtXmlUtility logError: message contents asString.
AbtXmlUtility logError: ''.
AbtXmlUtility logError: 'Response->'.
" NOTE: The output message is not stored in the message
context. "
AbtXmlUtility logError: (
anSstWSMessageContext container serializationManager
serialize: anSstWSMessageContext currentMessage
context: anSstWSMessageContext )
] fork ].
factory
register: pluggableHandler
named: 'wsHttpServerResponseHandler' inNamespace: factory
globalNamespace
To disable the tracing code, execute the snippet below:
| factory |
factory := ( SstWSContainer containerNamed:
'VastSampleServerContainer' ) handlerFactory.
factory
register: SstWSNoOperationHandler default
named: 'wsHttpServerResponseHandler' inNamespace: factory
globalNamespace
-------------------------------
How can I print incoming and outgoing SOAP messages on my Web services
client?
The message handler chain can be modified to add code that dumps the
contents of the SOAP message and response.
| factory pluggableHandler |
factory := ( SstWSContainer containerNamed: 'VastSampleClientContainer'
)
handlerFactory.
pluggableHandler :=SstWSPluggableHandler new
invokeBlock: [ :anSstWSMessageContext | | message |
[
message := anSstWSMessageContext
propertyNamed: ##wsTransportMessageRequest.
AbtXmlUtility logError: 'Request->'.
AbtXmlUtility logError: message asString.
AbtXmlUtility logError: ''.
AbtXmlUtility logError: 'Response->'.
" NOTE: The output message is not stored in the message
context. "
message := anSstWSMessageContext
propertyNamed: ##wsTransportMessageResponse.
AbtXmlUtility logError: message header debugPrintString.
AbtXmlUtility logError: message contents asString
] fork ].
factory
register: pluggableHandler
named: 'wsHttpClientResponseHandler'
inNamespace: factory globalNamespace
To disable the tracing code, execute the snippet below:
| factory |
factory := ( SstWSContainer containerNamed:
'VastSampleClientContainer' ) handlerFactory.
factory
register: SstWSNoOperationHandler default
named: 'wsHttpClientResponseHandler'
inNamespace: factory globalNamespace
-------------------------------
How can I clean up the sockets and active HTTP servers in my image?
The script below shuts down all active HTTP servers, and terminates all
active sockets.
[true] ensure:
["Stop a running system and clean everything out"
SstHttpServletEngine allInstances
do:[:e | e shutDown. e clear. e become: nil].
SstHttpServer allInstances
do:[:e | e shutDown. e clear. e become: nil].
Processor allProcesses
do: [:s | (s == UIProcess currentUI) ifFalse: [s basicTerminate]].
Processor reschedule.
SstApplicationContext clearAll.
SciSocketManager default closeAllSockets.]
-------------------------------
How does VAST default serializer determine the XML schema type for an
object that is defined as 'anyType'?
The algorithm for processing 'anyType' and for processing 'subtypes' is
very similar.
A new mapping spec is introduced (contained in 'abtvast.map') to
represent the Smalltalk namespace. The new mapping spec is intended to
describe how Smalltalk objects should map to XML schema types. For
typical mapping specs, it is possible to have multiple types map to the
same object; therefore, determination of a schema type from an object
instance is ambiguous. The Smalltalk namespace mappings remove
ambiguity because each object maps to a single schema type.
For many cases, it is not necessary to refer to the Smalltalk mapping
spec in order to determine a proper type mapping. The Smalltalk
namespace exists strictly to remove ambiguity when the same class can
map to multiple types.
When trying to determine the 'actual' type for an object, VAST does the
following:
- Check the schema of the base schema type to see if there is a more
specialized type that matches the class name of the object being
serialized.
- Try to find a mapping for the class name of the serialized object and
use the mapping to determine the actual schema type. The mapping is
searched for in:
1) Smalltalk mapping namespace
2) Base type namespace
3) All other visible namespaces (namespaces visible at that point in
serialization of the object)
For types other than 'anyType', if no 'specialized' type is found, the
'baseType' is assumed to be the serialization type.
For an 'anyType', if no 'specialized' type is found, a type definition
is constructed based on the class shape. The type is created in the
"VisualAge Smalltalk" namespace.
The "Smalltalk" namespace is settable in the serialization
configuration. The default value is 'urn:Vast' and is globally
settable in the pool variable AbtXml
Constants::AbtXmlSmalltalkNamespace.
-------------------------------
How can I disable validation during WSDL parsing?
AbtXmlObjectCache current
addDeserializationConfiguration:
(AbtXmlDeserializationConfiguration newWsdlConfiguration
validate: false)
named: 'http://schemas.xmlsoap.org/wsdl/'.
-------------------------------
How can I enable code page conversion of SOAP messages during
serialization?
Add an 'XmlSerializationEncoding' entry to the [Xml] stanza of your
application's .ini file as shown below.
[Xml]
DefaultResourceQualifier=D:\vast\b49\xml\
XmlSerializationEncoding=UTF-8
The value for this entry should be the target encoding for the
serialized SOAP message. The VAST Web services support will always
attempt to serialize SOAP messages using the specified encoding.
For less common encodings, it may be necessary to add a code page
mapping using API in AbtXmlStreamConverter to map the specified
encoding value to a valid code page supported by the platform.
AbtXmlStreamConverter mapEncoding: 'UTF-8' toCodePage: 65001
-------------------------------
How can I deploy commonly used schemas to a Web services container?
The deployment descriptor contains a <schemaUrls> block for this
purpose. Schemas that are imported by deployed WSDL documents are
automatically deployed to the container and do not need to be included
in the <schemaUrls> block of the deployment descriptor.
<schemaUrls>
<schemaUrl>
http://schemas.xmlsoap.org/ws/2002/07/secext/
</schemaUrl>
</schemaUrls>
Use the <schemaUrls> block to:
- Specify XML schemas required to provide supplemental functionality
(ie. SOAP 1.2, WS-Security )
- Override schemas that are already deployed to the global XML object
cache (ie. WSDL, SOAP)
-------------------------------
How can I enable a VAST container to process SOAP 1.2 messages?
VAST Web services containers can be configured to enable processing of
SOAP 1.2 messages. This is accomplished by deploying SOAP 1.2 schemas
and mapping specifications to the server container. See the sample
directory /samples/sstws/soap12/Readme.txt for additional information
about configuring a Web services container for SOAP 1.2.
The same Web services container can be used to process SOAP 1.1 and
SOAP 1.2 messages.
-------------------------------
How can I enable a VAST client service to send SOAP 1.2 messages?
VAST Web services client containers can be configured to enable
processing of SOAP 1.2 messages. This is accomplished by deploying
SOAP 1.2 schemas and mapping specifications to the client container.
In addition, SstWSService instances contain accessors to allow the SOAP
1.2 namespace to be specified for outgoing SOAP messages.
ie)
| service namespace |
namespace :=
'http://www.SstWSInsurancePolicyInterface.com/SstWSInsurancePolicyInterface-impl'.
service := (SstWSContainer containerNamed: 'MyContainer')
serviceManager
serviceNamed: 'SstWSInsurancePolicyInterface'
inNamespace: namespace.
service
sstSoapEnvelopeNamespace: SstSoap12Constants::SstSoap12EnvelopeNamespace.
See the sample directory /samples/sstws/soap12/Readme.txt for
additional information about configuring a Web services
container for SOAP 1.2.
-------------------------------
How can I configure client services to pass WS-Security information?
The schema (http://schemas.xmlsoap.org/ws/2002/07/secext/) must be
managed by the serializationManager of the Web services container.
This is accomplished by modifying the client deployment descriptor to
include the required schema.
ie)
<schemaUrls>
<schemaUrl>
http://schemas.xmlsoap.org/ws/2002/07/secext/
</schemaUrl>
</schemaUrls>
Authorization credentials can be specified in the SstWSService that is
being invoked causing those credentials to be passed automatically as
part of the message. The SstWSService contains accessors for getting
and setting HTTP authorization credentials (#sstAuthCredential:) as
well as WS-Security username tokens (#sstUsernameToken:). See the
sample directory /samples/sstws/ws_security/Readme.txt for additional
information and examples.
-------------------------------
How can I specify a custom servlet for processing incoming service
requests?
The default servlet for processing incoming Web services messages is
SstWSServlet. Developers may provide their own custom servlet if more
sophisticated rocessing is required. To enable an alternative servlet
using the default http transport strategy, execute code like that shown
below:
SstWSHttpNetworkTransportStrategy defaultServletClass:
MyWebServicesServlet
-------------------------------
How can I make use of custom SST transports for invocation of remote
service operations?
The container configuration supports transport mappings that are used
to map url schemes to the registered SST transport schemes used for
invocation.
The #urlScheme setting can specify a full URL name to enable special
processing for a specific resource location, or the value can be a
scheme prefix (ie. 'http' or https') for general cases.
The #transportScheme is the identifier for an SstTransport
configuration that describes the details of the underlying
communications protocol.
<!-- transportMappings is an optional element that
appears after the </managers> end tag
in the container deployment descriptor. -->
<transportMappings>
<transportMapping urlScheme="http" transportScheme="httpl" />
<transportMapping urlScheme="http://vasthost:63003" transportScheme="vasthost" />
<transportMapping urlScheme="https" transportScheme="testhttps" />
</transportMappings>
The code below accomplishes the same task:
| myContainer |
myContainer := SstWSContainer
containerNamed: 'VastSampleClientContainer'.
myContainer configuration
mapUrlScheme: 'http' toTransportScheme: 'httpl' ;
mapUrlScheme: 'http://vasthost:63003' toTransportScheme: 'vasthost'
mapUrlScheme: 'https' toTransportScheme: 'testhttps'
SST transport schemes must be registered in class SstTransport prior to
usage. See the class methods #serverTransportConfiguration and
registerPluginConfigurations in SstHttpCommunications for an example of
how transport configurations are created and registered.
-------------------------------
How can I map a Smalltalk Dictionary to XML?
The resource files 'sstaxis.map' and 'sstaxis.xsd' contain the rules
required for mapping Smalltalk Dictionary objects to/from XML.
Dictionaries are represented in XML as 'Map' elements in the namespace
'http://xml.apache.org/xml-soap'
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 <vast client directory> /xml
cp /opt/IBMvast/6.0/xml/*.* .
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.
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)
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/abtw
sac.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.
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.c om/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.
The following public methods are removed: AbtXmlSchema>>#abtXmlPrintOn:namespaces: AbtXmlSchemaComplexType>>#abtXmlPrintOn:namespaces: AbtXmlSchemaDeclaration>>abtXmlPrintOn:namespaces: These methods were not used by supported versions of the VAST XML support and should not affect user applications.
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.
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 2006. All rights reserved.
[10/9/2006 - 1:46:41 PM]