WebSphere Application Server for System i

Overview

Support

Resources

Release Notes for WebSphere Application Server Express Version 5.0.2.x for iSeries

This document contains Release Notes for WebSphere Application Server - Express Version 5.0.2.x for iSeries. The Release Notes contain information about known problems and their work arounds. This document also includes some supplemental information for topics covered in the WebSphere Application Server - Express documentation. This version replaces all earlier versions of the release notes.

Note: All items apply to V5.0.2.x unless otherwise noted.

These notes will be updated periodically. Please see the WebSphere Application Server - Express for i5/OS Web site for the most up-to-date information.

When troubleshooting, be sure to search the WebSphere Application Server for i5/OS FAQ (Frequently Asked Questions) database.

See the Installation documentation for the most up-to-date, step by step instructions on installing the product and creating the initial configuration.

Table of Contents

Documentation
Installation Instructions
Fix Warning
PTF Information
Known Problems and Restrictions 

Product Installation QShell Scripts Integrated Console Administrative Console and Command Line Tools Workstation Tools Application Server Data Access Servlets and JavaServer Pages (JSPs) XML Business Applications - IBM Telephone Directory Web Services HTTP Server WebSphere - Express - Domino coexistence Security National Language Version Issues/Limitations

Documentation

The most up-to-date documentation can be found on the WebSphere Application Server - Express for i5/OS Web site documentation page.

What's New

1. New parameter -trace for startServer
2. New scripts:
   
   • servicetools
     
   • checkprereqs
     
   • prerequisite validator tool
   • port validator tool
     
3. How to Migrate your web services document
4. Crtwasinst no longer supports the -extssl parameter
5. New parameters for collector script
6. Web services

   New to WebSphere Application Server - Express Version 5.0.2 is support for Java API for XML-Based RPC (JAX-RPC) and Java Specification Request (JSR) 109: Implementing Enterprise Web Services. The Apache SOAP version of Web services (available in Application Server - Express Versions 5.0 and 5.0.1) is deprecated and may be removed in a future release. It is recommended that you migrate your Web services applications to the new specifications.

   Version 5.0.2 Web services also supports the Web Services Security Specification (WS-Security). WS-Security provides a standard set of SOAP extensions that can be used to develop secure Web services. These extensions are configured at the application level, in the deployment descriptor for the Web services application.

   Graphical support for configuring the WS-Security SOAP extensions is available in WebSphere Development Studio for iSeries, Version 5.1 (available October 17, 2003). See the WebSphere Development Studio for iSeries product site for more information. You can also configure Web services security with the WebSphere Application Server Toolkit (for workstation platforms), available for download from WebSphere Application Server Support. Both tools are based on Eclipse technology and have similar interfaces.

   For more information about Version 5.0.2 Web services, see the Web services topic in the product documentation.

Back to top

Installation Instructions

Installation Instructions for WebSphere Application Server - Express for i5/OS V5.0.2 Group PTF

WebSphere Application Server - Express for i5/OS V5.0.2 is a fix release that is shipped in the form of a Group PTF (Program Temporary Fix). Please see the Install section in the Known Problems and Restrictions section of this document before beginning the install.

The following instructions describe how to install the V5.0.2 group PTF:

• Installation of the group PTF on systems with multiple instances will notice an increase in the amount of time required to apply PTFs.  The operator may notice a group PTF install time increase of several minutes per instance.
• Verify that WebSphere Application Server - Express V5.0 is installed on the server before proceeding with the V5.0.2 installation. V5.0 must be installed on the system before the V5.0.2 group PTF can be installed. The following instructions describe how to determine if WebSphere Application Server - Express V5.0 is installed:
  1. Run the following command from an iSeries command line:

  2.         DSPSFWRSC
     

  3. Page down until you find 5722IWE. Make sure option 2 of the 5722IWE product is listed. If option 2 is not installed, the WebSphere Application Server - Express is not installed.
  4. Press PF11 to display the Release column. A release value of V5R1M0 indicates that version 5.0 is installed.
• Install the Group PTF. The recommended steps for installing the group PTF are:
  1. Insert the group PTF CD (the first CD if more than one) into the CD-ROM drive of your iSeries system.
  2. Place the system in restricted state (ENDSBS SBS(*ALL)).
  3. Go to the Work with PTFs menu (GO PTF).
  4. Select option 8 .
  5. Enter the appropriate information so that all PTFs for all products on the CDs are loaded and applied, and the system is automatically IPL'd.
  Notes:
  • The WebSphere Application Server - Express PTFs that are part of the group PTF are all corequisites of each other. Do not install or remove individual WebSphere Application Server - Express PTFs. Instead, all of the WebSphere Application Server - Express PTFs that are part of the Group PTF must be installed or removed in their entirety.
  • The group PTF also includes PTFs for other products. If you install or re-install one of these products after applying the WebSphere Application Server - Express group PTF, you must re-apply the group PTF to pick up the PTFs for the newly installed product.

  Please see the PTFs section in this document for more information on the WebSphere Application Server - Express for i5/OS V5.0.2 group PTF.  

• Start the HTTP Server Administration Interface using the following command:

  STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)
           
  

• Use the HTTP Server Administration Interface to start your WebSphere Application Server - Express instances.
• Start any HTTP Server instances you are using with WebSphere Application Server - Express.  Use the HTTP Server Administration Interface or the following command:

           STRTCPSVR SERVER(*HTTP) HTTPSVR(instance_name)
                 
               
  

Back to top

Fix Warning

The WebSphere Application Server - Support Web site provides individual fixes for critical problems that are not part of a WebSphere Fix Pack. These fixes have not been tested against WebSphere Application Server - Express Version 5.0.2 for iSeries. Unless otherwise noted, these fixes should not be applied to your iSeries server. These fixes will be included in official fix packs for the product.

If you have a critical requirement for a fix, then please contact IBM Service.

Back to top

PTF Information

• Group PTFs SF99270 (V5R1) and SF99271 (V5R2) are available. The preferred time to apply them is after installing WebSphere Application Server Version - Express 5.0 for iSeries and preferably before the WebSphere Application Server - Express environment is first started or any additional WebSphere instances are created.
• The group PTFs SF99270 and SF99271 contain fixes for the IBM HTTP Server product, 5722-DG1 in support of the WebSphere Application Server - Express product, 5722-IWE.
• PTF requirements for WebSphere Application Server - Express Version 5.0.2 for iSeries are posted to the product Web site:
  • V5R1
  • V5R2

  Check this site often to verify that you are running the product with the latest required PTFs.

  Note: There is no matching workstation FixPak for Group PTFs SF99270 (V5R1) and SF99271 (V5R2).

Back to top

Known Problems and Restrictions

WebSphere Application Server - Express for i5/OS Product Installation

1. Note that WebSphere Application Server - Express is preinstalled with OS/400 V5R2 for some iSeries models. Before attempting to install the product, use the iSeries command GO LICPGM with option 10 to determine if the product 5722-IWE option 2 is already installed.

Back to top

QShell Scripts

1. The -timeout and -statusport options are not currently supported for the stopServer QShell script. Specifying these options results in the usage statement for the script being displayed.
2. The usage information returned by the '-help' parameter is not complete for all qshell scripts.
3. The '-instance' parameter is always required on the following scripts: crtwasinst, dltwasinst, dspwasinst, startserver, stopserver, serverstatus, chgwassvr, backupconfig, restoreconfig, GenPluginCfg, collector, showlog, JspBatchCompiler. Please see the WebSphere Application Server - Express Documentation Center for complete script usage information
4. A known problem exists when using national characters in instance names. Instances that are created with names that contain a character that is greater than 0x7f ASCII may create successfully, but they will not start. It is recommended that you limit your instance names to the following characters when you create a server using the crtwasinst script:
   • A through Z
   • a through z
   • 0 through 9
   • "_" and "-"
5. The name 'server1' is not allowed for a WebSphere - Express Application Server instance. Applications will not install properly into an Express server named 'server1'.

Back to top

Integrated GUI

1. The integrated GUI can only be used with WebSphere Application Server - Express application servers that have the same (case sensitive) name as the instance name that the application server is running in. Therefore, it is recommended that the both instance name and the application server name be the same. Note that a difference in the application server name and the instance name can occur when creating a server using the crtwasinst Qshell command.
2. The integrated GUI can not be used to administer an application server that is also being managed concurrently with the wsadmin utility or the administrative console.
3. A known problem exists when using national characters in application server names. Application servers that are created with names that contain a character that is greater than 0x7f ASCII may create successfully, but they will not start. It is recommended that you limit your application server names to the following characters:
   • A through Z
   • a through z
   • 0 through 9
   • "_" and "-"
4. The name 'server1' is not allowed for a WebSphere - Express Application Server instance. Applications will not install properly into an Express server named 'server1'.
5. A known problem exists when attempting to update an application using the 'Update' button on the Manage Installed Applications form of the Integrated GUI. If the Application Name was changed when the application was initially installed using the Install New Application Wizard, the application will not update successfully unless the Application Name defined in the updated EAR/WAR file is the same as the name specified upon initial install. To avoid this problem, do one of the following:
   • Change the Application Name in the updated application archive by specifying it in the deployment descriptor of the application (using 'display name' in the application.xml for an EAR file, or web.xml for a WAR file). This display name should match the name originally specified in the application install wizard.
   • Uninstall and install the updated application accepting the default value that is provided in the Application Name field during the initial install of the application. All further updates will use this same default value (assuming the display name is not changed in the EAR/WAR at a later date)
6. If the Administrative Console application has been removed from a WebSphere - Express instance and reinstalled from /QIBM/ProdData/WebASE/ASE5/installableApps/adminconsole.ear, the application cannot be accessed from the Integrated GUI using the 'Launch Express Console' link. To maintain this link, when reinstalling the Administrative Console using the Install New Application Wizard, change the Application Name to 'adminconsole' (lower-case, no spaces) instead of the default 'Admin Console'.

Back to top

Administrative Console (GUI) and Command Line Tools

1. The administrative console help text provides information about features and functions that are not supported by WebSphere Application Server - Express. For example, EJB help documentation is provided, but not supported by WebSphere Application Server - Express.
2. The administrative console's application install menu displays information about Enterprise Java Beans (EJBs) even though EJBs are not supported by WebSphere Application Server - Express.
3. The administrative console does not support using the browser Back and Forward buttons. Use of these buttons can cause intermittent problems. Use the Back or Cancel buttons on the administrative console panels instead.

4. Attaching wsadmin to a remote server process running the following AdminApp commands results in an error:

   edit
   editInteractive
   export
   exportDDL
   install
   installInteractive uninstall

   To work around this problem, do one of the following:

   • Invoke the AdminApp command with the server process connected locally.
   • Specify the cell option when running these commands against a remote server.
     For example:

     $AdminApp uninstall samples {-cell myCellName}
                      
     

     Note: This work around does not work for edit, editInteractive, install, and installInteractive commands if wsadmin is running from a system with only the standalone scripting client installed.
5. When any LDAP user or group filter is modified in the Advanced LDAP settings panel it is recommended that you click Apply instead of OK. Clicking OK takes you to the LDAP user registry panel, which contains the previous type (LDAP directory type) and not the Custom type as it is supposed to. Therefore, if you click OK or Apply in this panel (LDAP user registry), the old LDAP directory type (and hence the default filters of that directory) is saved resulting in your changes to the filters being overwritten. To avoid this you can do either of the following:
   • Click Apply in the Advanced LDAP settings panel. Then, to proceed to another panel, use the navigation on the left. If the navigation is used to access the LDAP user registry panel you should see that the directory type is changed to Custom.
   • Choose Custom type in the LDAP user registry panel. Click Apply and then change the filters by clicking the Advanced LDAP settings panel. In this scenario once the changes are completed you can click Apply or OK.
6. The administrative console Lightweight Third Party Authentication help panel is not correct. See the security section for the correct information.

7. When you click Test Connection for a 4.0 data source that is created by WASPostUpgrade during a migration from WAS V4.0.x, the following exception displays:

   DSRA8040I: Failed to connect to the Data Source.
   
   Encountered: java.lang.NullPointerException
                
   

   This exception occurs with 4.0 data sources created by the WASPostUpgrade tool during migration which do not have any custom properties.

   To avoid receiving the exception, create a valid DB2 custom property on the data source. For example, create a description in the Custom Property panel.

• Resizing your browser window when using Netscape to access the IBM WebSphere Application Server - Express administrative console can cause problems such as:

• If you resize your Netscape browser, you could get a "Data Missing" error. The error message disappears in 60 seconds.
• When connecting to the IBM WebSphere Application Server - Express administrative console from a Netscape browser, resizing the browser can cause an error 404 message to occur. This situation occurs because the browser reloads the frame when resizing the window.
  • To avoid getting the error message, you can refrain from resizing the Netscape browser window, or you can connect to the IBM WebSphere Application Server - Express administrative console using an Internet Explorer browser.

• You receive the following error messages when resizing Netscape Version 4.7:

  Error 0
  An error occurred while processing request:
  
  http://localhost:9090/admin/upload.do
  
  
  
    message:
  
  Details
  com.ibm.webshpere.servlet.error.ServletErrorReport:
  	 at java.lang.Class.newInstance0(Native Method)
  	 ...
  

  After resizing Netscape 4.7, Netscape has to reload the page just as it initially loads the page on the first request. For pages that do not expect POST data, it is not a problem. But for pages that do, Netscape 4.7 cannot retain the data.

• An error can occur when setting a trace specification from the administrative console if selections are made from both the Groups and Components lists. In certain cases, the selection made from one list is lost when adding a selection from the other list. To work around this problem, enter the desired trace specification directly into the Trace Specification entry field.
• While working with the right-hand panel of the administrative console to do administrative tasks, the browser screen blanks out intermittently.

To work around this problem, do one of the following:

• After the problem occurs, close the Netscape browser, log in again, and continue working.
• Use the Internet Explorer browser from a Windows machine.
• Use Netscape 7.x, Mozilla 1.x, Opera 5, or Konquerer browsers on the platform, depending on which is available. Although there is not formal support for these browsers, they have all been used successfully with the product and in many cases work better than the previous 4.7.x series of Netscape browsers.

• If you create or update a data source that points to a newly created J2C authentication data alias, Test Connection fails to connect until you have restarted the server so that the J2C authentication data is reflected in the run-time configuration. Any changes to the J2C authentication data fields require an application server restart for the changes to take effect.

If you use the Netscape browser to access the Web Services Security GUI panels, the drop down lists which are supposed to contain a blank line display "---???---" instead of the blank line.

This is because Netscape Version 4.79 does not properly interpret "" or " " as a blank.

This is in the signature method(), digest method(), canonicalization method() drop downs, and others when Netscape 4.79 is used to access the panels on an AIX system. This problem does not occur when you use Internet Explorer, which properly displays a blank line.

There is no workaround if you use Netscape 4.79, which is the supported level of Netscape for this release.

Currently, the pwbs_GetUrlPrefixesHelp.html file is incorrectly installed into the [INSTANCE_ROOT]/installedApps/nodename/adminconsole.ear/adminconsole.war/
com.ibm.ws.console.perftuningadmin/nl/en/pwbs_GetUrlPrefixesHelp.html directory and the [INSTANCE_ROOT]/ installedApps/nodename/adminconsole.ear/adminconsole.war/
com.ibm.ws.console.servermanagement/nl/en/pwbs_GetUrlPrefixesHelp.html directory. 

To find the pwbs_GetUrlPrefixesHelp.html file from the Publish WSDL panel, you need to copy the file into the [INSTANCE_ROOT] /installedApps/nodename/adminconsole.ear/adminconsole.war/
com.ibm.ws.console.webservices/nl/en/pwbs_GetUrlPrefixesHelp.html directory.
Where [INSTANCE_ROOT] is the root directory of your instance, e.g./QIBM/UserData/WebAS5/Base/default.

• Exception occurs when you create or modify configuration attribute that uses Java native type. The following exception occurs when you update a boolean type attribute: WASX7015E: Exception running command: "$AdminConfig modify $targetMappings {{enable false}}"; exception information: com.ibm.ws.scripting.ScriptingException: WASX7239E: Unexpected error setting attribute "enable" of type "boolean" to value "false." Additional information may be found in the trace log. The reason for this exception is that certain WebSphere Application Server, Version 5.0.2 configuration data use Java native types that are not recognized by a WebSphere Application Server, Version 5 or Version 5.0.1 wsadmin scripting client. The known Java native types include boolean, int, and long.
  To work around this problem, use a WebSphere Application Server, Version 5.0.2 wsadmin scripting client to connect to a Version 5.0.2 server to create or update the native type configuration data.
• The testConnection and getPropertiesForDataSource commands in the AdminControl scripting object are no longer supported as of 5.0.2.
  

• $AdminControl testConnection configId props

• $AdminControl getPropertiesForDataSource configId

• When viewing "Configuration Problems" (Troubleshooting->Configuration Problems), you may see:
  

[ServletException in:configproblems.validation.preferences]

Response already committed.

Back to top

Workstation Tools

1. The WebSphere Development Studio Client (WDSc) for iSeries contains function and documentation that may not apply to WebSphere Application Server - Express for i5/OS. See WebSphere - Express documentation to determine what functionality is supported.

Back to top

Application Server

1. The WebSphere Application Server - Express only supports one application server per server instance. Note that you can create multiple server instances, each running one application server.
   When starting a server, ignore NMSV0715W messages that occur in the SystemOut.log file of the server. These messages result from cell or node level configured EJB naming binding entries for enterprise beans in other servers. The WebSphere Application Server - Express run time should ignore these entries, but instead, flags them with NMSV0715W messages. Note that WebSphere Application Server - Express does not support EJBs.

Back to top

Data Access

1. When a new WebSphere Application Server instance is created, a copy of the file /QIBM/ProdData/WebAS5/Base/config/templates/system/
   jdbc-resource-provider-templates.xml is copied into the directory /QIBM/UserData/WebAS5/Base/instance_name/config/templates/system/ . This is a modifiable xml file that sets up the default custom properties values for JDBC connections obtained from a datasource. The ProdData version of this file will be copied to the UserData directory so new datasources will use the correct default values. The existing jdbc-resource-provider-templates.xml in the directory /QIBM/UserData/WebAS5/Base/instance_name/config/templates/system/ will be renamed with the following format:

   jdbc-resource-provider-templates_ISO date.BAK
   

   where ISO date will be of the format '20030128'.
   Any previous user modifications made to this file will need to be merged into the new version of the jdbc-resource-provider-templates.xml file.
2. The DB2 Universal JDBC type 4 driver is supported in WebSphere Application Server, Version 5.0.2. The minimum fix pack level is DB2 V8.1 FP1. The DB2 Universal JDBC type 4 driver does not support XA transaction and it is only supported in WebSphere Application Server, Version 5.0.2 data sources.  Although the DB2 Universal JDBC type 4 driver can be used to access both iSeries and  non-iSeries DB2 databases,  it is recommended that  users continue using the IBM Developer Kit for Java JDBC driver (Native JDBC driver) for accessing the local iSeries database, and the IBM Toolbox for Java JDBC driver for accessing remote iSeries databases.

3. There is a known problem on mapping StaleConnectionException. When you see the following exception stack, it is mapped to StaleConnectionException:

   Error Code = 0
   SQL State = null
   com.ibm.db2.jcc.b.DisconnectException: A communication error has been detected. Communication protocol being used: {0}. Communication API being used: {1}. Location where the error was detected: {2}. Communication function detecting the error: {3}. Protocol specific error codes(s) {4}, {5}, {6}. TCP/IP SOCKETS Agent.sendRequest() OutputStream.flush() Connection reset by peer: socket write error * 0
   at com.ibm.db2.jcc.c.a.a(a.java:329)
   at com.ibm.db2.jcc.c.a.u(a.java:302)

4. The following issue refers to the use of the DB2 Universal JDBC type 4 driver involved in non-iSeries DB2 database access.
   Deadlock results from accessing two different rows in a DB2 table when the next key is not locked for all INSERT and DELETE statements.

   To eliminate the deadlock, set the DB2_RR_TO_RS environment variable from the DB2 command line window. Setting this environment variable causes the following: 

   • If RepeatableRead (RR) is your chosen isolation level, it is essentially downgraded to Read Stability (RS).  
   • If you chose a different isolation level and the DB2_RR_TO_RS environment variable is turned on, scans of the database skip rows that are deleted but not committed. This activity occurs even if the row qualified for the scan. The skipping behavior affects the RR, RS, and Cursor Stability (CS) isolation levels.

5. When enterprise beans with container-managed persistent (CMP) types that have any VARCHAR FOR BIT DATA columns defined on a DB2 table are deployed in the DB2 universal JDBC type 4 driver to persist the data, an SQLException of illegal conversion is thrown at run time.

   This exception only occurs when you use the DB2 universal JDBC type 4 driver and with the deferPrepares property being set to true. When the deferPrepares property is set to true, the DB2 universal JDBC type 4 driver uses the standard JDBC data mapping.

   Currently, the generated deployed code does not follow the standard JDBC specification mapping. The failure at execution time is because of a problem in the tool that prepared the enterprise beans for execution.

   To avoid receiving this exception, choose one of the following options:

   • Set the deferPrepares property to false in the data source configuration.
   • Do not use the DB2 universal JDBC type 4 driver if your table has any VARCHAR FOR BIT DATA or LONG VARCHAR FOR BIT DATA columns. Use the DB2 legacy CLI-based JDBC driver to persist the data.

6. Caching of connection handles across servlet methods is limited to Java Database Connectivity (JDBC) and Java Message Service (JMS) resources. Other non-relational resources, such as Customer Information Control System (CICS) or IMS, currently cannot have their connection handles cached in a servlet. This limitation only applies to single-threaded servlets since multithreaded servlets do not allow caching of connection handles.

   To work around this problem, you need to get, use, and close the connection handle within each method invocation.

7. Enabling batchUpdate when running WebSphere Application Server with the DB2 Legacy CLI-based JDBC driver is ignored by the WebSphere Application Server run time due to a problem in DB2 which can cause data integrity problems.

   If you want to use batchUpdate for WebSphere Application Server, Version 5.0.2, run WebSphere Application Server with the DB2 Universal JDBC driver instead of the DB2 Legacy CLI-based JDBC driver.

8. If you have created a JDBC Provider scoped to the cell-level which uses a WebSphere variable for the Classpath property (for example, ${OS400_TOOLBOX_JDBC_DRIVER_PATH}) which is defined in the node-level variables.xml file, the test connection function will fail with an error indicating "undefined variable: variable_name" where variable_name is the name of variable specified for the Classpath property of the JDBC provider.

   The workaround for this problem is to define the WebSphere variable at the cell-level as well. To view and define WebSphere variables from the administrative console, expand Environment and click the Manage WebSphere variables link.
   This change in behavior is a permanent change. Cell level resources have access to cell-level variables. Node level resources have access to cell-level and node-level variables. Server level resources have access to cell-level, node-level and server-level variables. If a variable is specified at more than one level, the variable which is closest in scope to the scope of the resource is used.

9. Changes are made to the Java Database Connectivity providers in WebSphere Application Server V5.0.2.
   The following changes are made to the Java Database Connectivity (JDBC) providers in WebSphere Application Server V5.0.2:
   
   • WebSphere Application Server V5.0.2 provides a new JDBC provider for DB2:DB2 Universal JDBC driver provider. Use this JDBC provider to test the new DB2 Universal JDBC type 4 driver. This provider only supports 5.0 data source in WebSphere Application Server, Version 5.0.2. To distinguish between this new jdbc provider and the existing DB2 type 2 jdbc provider, V5.0.2 changes the name of the provider in the jdbc-resource-provider-templates.xml file to match the provider with the name.
   • It is recommended for performance reasons that  users continue using the IBM Developer Kit for Java JDBC driver (Native JDBC driver) for accessing the local iSeries database, and the IBM Toolbox for Java JDBC driver for accessing remote iSeries databases.
10. When using the EncAuthDataFile script, the input file provided must be in codepage 819.
    • To create a new file in CCSID 819 from QSHELL, do the following:
      1. From a QSHELL prompt, type: touch -C 819 /yourPathAndFileName, then press the Enter key.
      2. Use your favorite editor to edit the file as desired.
    • To create a new file in CCSID 819 from an OS400 system prompt, do the following:
      1. On an OS/400 command line, type the following:  EDTF (EDTF '/yourPathAndFileName'), then press the Enter key.
      2. Press F15 (Shift+F3) for Services.
      3. For selection, type 5 for Change CCSID of file.
      4. Change the value of Change CCSID of file to 00819.
      5. Press the Enter key to accept the changes.
      6. Press F3 to exit the Services screen.
      7. On the main Edit File screen, press F2 to save the file.
      8. Type your properties file text, and press F2 to save and F12 to exit.
    • To convert an existing file that has the wrong CCSID, do the following:
      1. If you have an existing properties file that does not work because it is in some other CCSID, use the CPY command to copy the properties file to a new file, specifying TOCODEPAGE(819) to change the CCSID.
         

Back to top

Servlets and JavaServer Pages (JSPs)

1. Performance changes to the WebSphere HTTP Plugins may result in InterruptedIOTimeout exceptions while reading large requests, such as receiving file uploads to a servlet.  To circumvent the problem, increase the Connection I/O Timeout value on the Web Container of your application server.
   • Drill Down to Servers -> Application Servers -> <Server> -> WebContainer -> HTTP Transports -> <Transport>
     Click Customer Properties and add a property named ConnectionIOTimeOut and set to the desired value (in seconds).  Restart the application server for the changes to take effect.
     

Back to top

XML

1. Programs containing the Xerces parser routine that work on WebSphere Application Server Version 4.0.x might not work on WebSphere Application Server - Express Version 5.0.2.

Versions of Xerces prior to 2.0.0, including the versions shipped with WebSphere Application Server Version 4.0.x, were not J2EE1.3 compliant. In order to meet J2EE1.3 certification constraints (DOM2/SAX2/JAXP1.1 (and no higher)), WebSphere Application Server - Express Version 5.0 requires use of XML4J4.0.0 (Xerces 2.0 + bug fixes). In Xerces versions prior to 2.0.0 and Xalan versions prior to 2.2, the DOM, SAX, and JAXP APIs were bundled inside of the xerces.jar and xalan.jar files. In the most recent versions, these non-apache XML APIs have been moved into a separate JAR file in the XML-commons Apache project. These common XML APIs are required by the specifications and contained within the WebSphere Application Server - Express Version 5.0.2 j2ee.jar file. The cause of the problem is that the classloader behavior mixes the classes that are required by J2EE1.3 with those of the older Xerces implementation.

To work around this problem, use the Xerces parser routine version that ships with WebSphere Application Server - Express Version 5.0.2.

Back to top

Business applications

• Note that IBM Telephone Directory is installed and configured with OS/400 V5R2 for some iSeries models. Before attempting to install the product, use the iSeries command GO LICPGM with option 10 to determine if the product 5722-IWE option 3 is already installed. Refer to the IBM Telephone Directory configuration documentation in InfoCenter to determine if the product is already configured.
• LDAP over SSL is not yet fully supported by IBM Telephone Directory. You may specify the -Z option on the itdsetup script to set up your LDAP server using SSL connections. However, the IBM Telephone Directory application currently will not use SSL connections to communicate with your LDAP server. It will only use non-SSL connections. A solution to this problem will be available soon.
• IBM Telephone Directory will not function properly in a WebSphere - Express instance where Global Security is enabled and Java 2 Security is enforced. To use IBM Telephone Directory in a secure instance, uncheck 'Enforce Java 2 Security' on the Global Security configuration page in the Administrative Console. This option is checked by default when Global Security is enabled.

Back to top

Web Services

1. Universal Description, Discovery, and Integration 4J (UDDI4J) is a class library that provides an API used to interact with a UDDI Registry.

   Two class libraries are provided for UDDI4J in the /QIBM/ProdData/WebASE/ASE5/lib subdirectory:

   • uddi4j.jar supports Version 1 of the UDDI API. This is provided for compatibility with applications that have been written using UDDI Version 1, and the classes in this class library are deprecated.
   • uddi4jv2.jar supports Version 2 of the UDDI specification. The class in this library should be used by any application using UDDI4J to communicate with a Version 2 UDDI-compliant registry.
2. The Web services gateway does not support session management and maintenance of deployed target services using HTTP cookies. However, you can do this using Simple Object Access Protocol (SOAP) headers.
3. When you edit the service security configuration for a Web service in the gateway (for more information see the product documentation article, "Enabling Web Services Security (WS-Security) for the gateway"), you cannot select ID Assertion. You can navigate to the section Accepted identification methods, and select the ID Assertion check box, but when you click Apply Changes this change is not applied.

4. A WebServicesFault exception is thrown by the application server run time for certain Web Services Description Language (WSDL) files that defines operations with the document style and literal use and use the Simple Object Access Protocol (SOAP) header to transmit the input data.

   If the WSDL files define an operation with document style and literal use and this operation maps the input to the SOAP header, the Web services run time fails to find the right operation for the target service and a WebServicesFault exception is thrown.

   To solve the problem, you must change the WSDL files so that the previously noted operation does not have any input that uses the SOAP header to transmit the data.

Back to top

HTTP Server

1. Communication between the HTTP server plugin and WebSphere application server - Express can be done via HTTP or HTTPS. The additional products necessary to run with HTTPS may or may not already be installed on the iSeries. If the following message is in the HTTP server job log, the WebSphere HTTP server plugin detected it has been configured so it should use HTTPS when communicating with the app server, however, the required products for HTTPS communication were NOT installed on the iSeries.

   Joblog message:

   Plugin will continue to startup, however, SSL transport did not initilize. Secure communication between app server and plugin will NOT occur. To run with SSL, additional products may need to be installed: 1) OS/400 Digital Certificate Manager (5722-SS1 or 5769-SS1, option 34) 2) Cryptographic Access Provider 5769-AC1 (40-bit), 5722-AC2 or 5769-AC2 (56-bit), 5722-AC3 or 5769-AC3 (128-bit)

2. V5.0.2.4+ An HTTP server configured to communicate with a WebSphere - Express Application Server instance at the 5.0.2.4 fix level or later may not function properly after moving to i5/OS (OS/400 V5R3.) If requests cannot be served successfully though the HTTP server, the problem could be due to an incompatibility issue that can be resolved by applying the Express 5.0 (5722IWE) V5R3 Group PTF (SF99272.)

Back to top

WebSphere - Domino coexistence

1. If you are accessing Domino data from your WebSphere - Express Applications and need NCSO.JAR in your classpath, you may have to point to it in a different place after upgrading Domino to version 6.5 or 6.0.3 or later versions.  The prior Domino releases had NCSO.JAR in /qibm/proddata/lotus/notes/shared, which is being removed in the 6.5 and 6.0.3 releases of Domino.
   
   Beginning with Domino versions 6.0.3 and 6.5, you should use:
   /QIBM/ProdData/Lotus/Notes/DATA/Domino/Java/NCSO.JAR or /xxxxxxxx/Domino/Java/NCSO.JAR (where /xxxxxxx is the data directory of a Domino Server instance).
   

Back to top

Security

1. If your application uses the java.net.URLConnection class it may throw java.lang.NullPointerException with com/ibm/ws/orbimpl/transport/protocol/https/HttpsURLConnection.connect() contained in the exception stack. The solution is to remove the URL provider (Samples URL Provider - https) from your WebSphere configuration. From qshell, execute the following wsadmin command, replacing &ltinstance_name> with your instance name, and restart the application server.
   
   

   /QIBM/ProdData/WebASE/ASE5/bin/wsadmin -instance &ltinstance_name>
   
   -conntype NONE -c '$AdminConfig remove
   
   [$AdminConfig getid /URLProvider:Samples\
   
    URL\ Provider\ -\ https/]'
   		
   

2. Some of the links from the following WebSphere Application Server security windows to their corresponding help files are incorrectly mapped:

   Environment > Naming > CORBA Naming Service Users

   Environment > Naming > CORBA Naming Service Users > Add

   Environment > Naming > CORBA Naming Service Groups

   Environment > Naming > CORBA Naming Service Groups > Add

   System Administration > Console Groups > Add

   Note: In the System Administration > Console Groups > Add window, the links to the help located next to Group Description and Role Description are correct. However, the link to the help text at the top of the help window is incorrect.

   If you access a help file that does not correspond to the appropriate WebSphere Application Server window, use the following table to locate the correct help information. When you access the incorrect help file, find the listing of help files located under Core Console on the left side of your current help file window and click the appropriate link.

   Window path	Correct Help file
   Environment > Naming > CORBA Naming Service Users	CORBA Naming Service users settings
   Environment > Naming > CORBA Naming Service Users > Add	CORBA Naming Service users settings
   Environment > Naming > CORBA Naming Service Groups	CORBA Naming Service groups
   Environment > Naming > CORBA Naming Service Groups > Add	CORBA Naming Service groups
   System Administration > Console Groups > Add	Console groups settings

3. In WebSphere Application Server - Express, Version 5.0.1 and Version 5.0.2, the distinguished name is normalized according to the Lightweight Directory Access Protocol (LDAP) specification. In WebSphere Application Server - Express, Version 5, the normalization of the distinguished name is not done. The normalization consists of removing spaces in the base distinguished name before or after commas and equal symbols.

   An example of a non-normalized base distinguished name is "o = ibm, c = us" or "o=ibm, c=us". .

   An example of a normalized base distinguished name is "o=ibm,c=us".

   It is preferred that the distinguished name is manually normalized when you enter the base distinguished name in the configuration. In WebSphere Application Server - Express, Version 5.0.2 and higher version, the normalization occurs automatically at the run time.

   When a WebSphere Application Server - Express, Version 5.0.1 and Version 5.0.2 system, which always has a normalized distinguished name, sends a security token to a WebSphere Application Server - Express, Version 5 system that contains a non-normalized distinguished name, the request is rejected due to the mismatched distinguished names during authorization. A common example of a request that fails is when a WebSphere Application Server - Express, Version 5 node is synchronizing the configuration from a WebSphere Application Server - Express, Version 5.0.1 and Version 5.0.2 deployment manager. Another example is that a request fails when a WebSphere Application Server - Express, Version 5.0.1 and Version 5.0.2 servlet or enterprise bean makes a downstream request to a WebSphere Application Server - Express, Version 5 enterprise bean. However, a request going from a WebSphere Application Server - Express, Version 5 system to a WebSphere Application Server - Express, Version 5.0.1 and Version 5.0.2 system does not fail.

   To ensure the interoperability between WebSphere Application Server - Express, Version 5, Version 5.0.1, and Version 5.0.2, manually normalize the base distinguished name in the LDAP configuration on a WebSphere Application Server - Express, Version 5.0 system by removing all the spaces before and after the commas and equal symbols.

4. The following JavaMail-related Java 2 security exceptions might be reported in the system log file when the Web services applications run with attachments in the Simple Object Access Protocol (SOAP) messages.
   

   java.security.AccessControlException: access denied (java.io.FilePermission
   
   /QIBM/ProdData/Java400/JDK13/lib/javamail.providers read)
   

   java.security.AccessControlException: access denied (java.io.FilePermission
   
   /QIBM/ProdData/Java400/JDK13/lib/javamail.address.map read)
   

   These exceptions are benign. This is not an application or system problem because the JavaMail anticipates the exceptions and handles them appropriately. The WebSphere SecurityManager is rather verbose in logging possible violations of the Java 2 security access control exceptions.

   However, you may also see Java 2 security exceptions which are not benign, i.e. failure to access mail.jar and activation.jar. This is due to the  incorrect permissions for mail.jar and activation.jar in the app.policy file. The mail.jar and activiation.jar files are located in directory ${was.install.root}/java/extlib instead of ${was.install.root}/java/jre/lib/ext. If this situation is a problem, change the permission settings for JavaMail in the <USER_INSTALL_ROOT>/config/cells/<node_name>/nodes/<node_name>/app.policy file.  Initially, the permissions for JavaMail are as follows:

   grant codeBase "file:${application}" {
   

   // The following are required by Java mail
   

   permission java.io.FilePermission
   
   "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}mail.jar", "read";
   

   permission java.io.FilePermission
   
   "${was.install.root}${/}java${/}jre${/}lib${/}ext${/}activation.jar", "read";
   

   };
   

   After making the changes the permissions should appear as follows:
   

   grant codeBase "file:${application}" {
   

   // The following are required by Java mail
   

   permission java.io.FilePermission
   
   "${was.install.root}${/}java${/}extlib${/}mail.jar", "read";
   

   permission java.io.FilePermission
   
   "${was.install.root}${/}java${/}extlib${/}activation.jar", "read";
   

   permission java.io.FilePermission
   
   "${user.home}${/}javamail.providers", "read";
   

   permission java.io.FilePermission
   
   "${java.home}${/}lib${/}javamail.providers", "read";
   

   permission java.io.FilePermission
   
   "${user.home}${/}javamail.address.map", "read";
   

   permission java.io.FilePermission
   
   "${java.home}${/}lib${/}javamail.address.map", "read";
   

   };
   

   For further details, consult with the InfoCenter article, "JavaMail security permissions best practices." However, note that the article shows incorrect permissions for mail.jar and activation.jar.
5. In the administrative console, when you click Import Keys in the Lightweight Third Party Authentication (LTPA ) panel multiple times in the same session and save it each time, the following message might be displayed on the console intermittently:

   Error 500
   
   An error occurred while processing request: /syncworkspace.do
   
   Message: Server caught unhandled exception from servlet [action]:
   
   java.lang.IllegalStateException
   

   Note: When you enter a wrong password in the LTPA panel during importing the keys and save the password, the save operation displays error messages in the WebSphere Status Window at the bottom of the administrative console. The keys are not updated in the run time and the old set of keys is used. However, the keys and the wrong password are saved in the configuration. This configuration is used during the next startup of the server(s)

   Therefore, if you save a wrong password accidentally, do not restart the server(s) unless the password is changed because the server(s) can fail to start if the keys and the password do not match.

   The cause for this error is that an invalidated session is referred to under some circumstances.

   To avoid receive this error, log out and log in back to the administrative console using a new window. Import the keys if necessary. If the problem persists, use the wsadmin tool.

   If you enter a wrong password and save the passowrd during importing the keys, you can use the following wsadmin commands to change the password to the correct value (the keys should be saved during the save operation). Do not restart any servers unless the password is changed for each of them.

   set LTPA [$AdminConfig list LTPA]

   set ltpaPw theCorrectPassword

   $AdminConfig modify $LTPA [list [list password $ltpaPw]]

   $AdminConfig save

6. V5.0.2.3+ The certificates in the Dummy key files for release 5.0 expire on March 17, 2005, for all versions prior to 5.0.2.3. For earlier versions, when the certificates expire, your server will not function correctly unless you have configured your WebSphere instance to use your own key and trust stores. Expired default certificates will prevent servers from initializing and will cause servers to stop operating if already started. New Dummy key files are provided with this group PTF. However, special actions may be required to update WebSphere instances. See this documentation for details.
7. A Web services security enabled application fails to start. You can receive an error message similar to the following:
   [6/19/03 11:13:02:976 EDT] 421fdaa2 KeyStoreKeyLo E WSEC5156E: An exception while retrieving the key from KeyStore object: java.security.UnrecoverableKeyException: Given final block not properly padded
   
   The cause of the problem is that the keypass (password) provided for a particular key in a Key Store is invalid. The Key Store passwords are specified in the KeyLocators elements of the bindings file(s) (ws-security.xml, ibm-webservices-bnd.xmi or ibm-webservicesclient-bnd.xmi).
   
   Check the keypass values for keys specified in the KeyLocators elements of the bindings file(s) and correct any that are incorrect.

Back to top

National Language Version Issues/Limitations

1. The help search in the administrative console does not return search results for Latin-1 terms that contain diacritical markings (for example, German "für", where the "u" includes an umlaut). To work around this problem, use the decimal representation of the character in the search term (for example, "f&#252;r").
2. A known problem exists when using national characters in instance names and application server names. Instances or application servers that are created with names that contain a character that is greater than 0x7f ASCII may create successfully, but they will not start. It is recommended that you limit your instance and application server names to the following characters when you create a server:
   • A through Z
   • a through z
   • 0 through 9
   • "_" and "-"

Back to top

IBM, iSeries, OS/400, RS/6000, AIX, Lotus, and WebSphere are trademarks of International Business Machines Corporation in the United States and/or other countries.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.