WebSphereTM Development Tools for iSeries V5.1 README file

This document contains prerequisite information for the WebSphere Development Tools for iSeries product. In addition, it includes any limitations of the product and information not included in the documentation.

The Installation Notes document contains all installation notes and procedures. This includes the use of response files and how to uninstall, and how to add or remove product components.

The Release Notes document describes product components, detailed system requirements, and migration scenarios, as well as the VisualAge(R) for Java(TM) Version 3.5.3 Enterprise Toolkit for AS/400(R) Release Notes.

Table of Contents

Documentation Changes

Important: How to selectively install or remove components
The Modify wizard allows you to add or remove components. The page with the text "Select components to be modified" should include this description:

To add a missing component, ensure its check box is selected.
To remove a component, clear its check box.
A complete description is in Installation Notes in section How to add or remove components after installation.

VisualAge RPG (VARPG)

For V5.1, the VARPG GUI Designer help has been updated to include new help information for:

No other updates have been made to this online help.

The HTML and PDF versions of the VARPG publications have not been updated. As such, they contain the following inaccuracies:

The DLL and LINKAGE keywords are not in the list of keywords for the following Language Sensitive help:

These keywords are also not in Table 33. Prototype, Procedure Interface, and Parameter Keywords in the VisualAge RPG Language Reference publication.

The following Part attributes have been added to VisualAge RPG.
Part Attribute Type Description Valid
Operation
Code
Subfile EditColumn numeric Returns the column number of the cell that is opened for editing. getatr
EditIndex numeric Returns the row number of the cell that is opened for editing. getatr
EditText text Returns the currently edited text of the cell that is being edited.
Returns empty string if no cell is opened for editing.
getatr
The following Subfile attributes are used for changing the order in which Subfile data columns are displayed. "data columns" refers to the order of the columns as specified at design time in the Field List page of the properties Notebook (a "data column" is specified with the ColNumber attribute). "view columns" refers to the order of the columns as they are displayed (a "view column" is specified with the new ViewColumn attribute). By default, the data columns and view columns are the same. If a user moves the display position of a column, only view columns change.
MapViewCol numeric When set to 1, this will display the subfile with columns re-arranged according to attributes ColNumber and ViewColumn. ColNumber is set to the data column number to move and ViewColumn is set to the destination column. Note that columns are not switched. View columns are shifted right or left as needed. setatr
ViewColumn numeric Set to the MapViewCol destination column. setatr
Example of code to map data column 2 to view column 4
C     Eval      %Setatr('FRA000000B':'SUBF':'ColNumber')=2
C     Eval      %Setatr('FRA000000B':'SUBF':'ViewColumn')=4
C     Eval      %Setatr('FRA000000B':'SUBF':'MapViewCol')=1
DColFRVCol numeric Returns the data column that corresponds to the column specified by ViewColumn. getatr
Example of code to get the data column of view column 4
C     Eval      %Setatr('WIN':'SBF':'ViewColumn')=4
C     Eval      DataCol4 = %Getatr('WIN':'SBF':'DCOLFRVCOL')
VColFRDCol numeric Returns the view column that corresponds to the column specified by ColNumber. getatr
Example of code to get the view column of data column 4
C     Eval      %Setatr('WIN':'SBF':'ColNumber')=4
C     Eval      ViewCol4 = %Getatr('WIN':'SBF':'VCOLFRDCOL')
SortAsc numeric Set to a data column for ascending sort of subfile data. setatr
Example of code to sort the 3rd column ascending
C     Eval      %Setatr('WIN':'SBF':'SortAsc')=3
SortDesc numeric Set to a data column for descending sort of subfile data. setatr
Example of code to sort the 3rd column descending
C     Eval      %Setatr('WIN':'SBF':'SortDesc')=3
Window PrintAsIs text Prints the image and maintains the aspect ratio. setatr
Image PrintAsIs text Prints the image and maintains the aspect ratio. setatr
Static-text DropValue numeric Set to 1 to allow the label value to be changed by a drop operation. Set to 0 to prevent the value from changing after a drop. The default is 1. For example, a static-text part has a label "Send Mail" and users are instructed to drag and drop an e-mail address onto the label to start a dialog to send e-mail. Set DropValue to 0 so that the label does not change to the e-mail address. setatr
Notebook Page OnTop numeric Set to 1 to change the specified page into the current page. Previously, users set the "PageNumber" of a notebook part to be N in order to make the N-th page the current page. This method can cause confusion when a page has been set to invisible because the runtime will delete the page from the notebook part. (When the page is set to visible again, the runtime will add it back into the notebook.) For example, if the following code is executed:
C            EVAL	   %SetAtr('frame':'page3':'visible')=0
C            EVAL          %SetAtr('frame':'notebook':'PageNumber')=3
then the current page is the 4th page (which is now the 3rd because the original 3rd page has been deleted).
Users can now use this line to set the 4th page the current page:
C            EVAL          %SetAtr('frame':'page4':'OnTop')=1
Without using the index number, it is clearer which page is the current one.
GETATR can be used to get the value of the OnTop attribute of a notebook page. It will return 1 if the page is the current page, otherwise it will return 0.
setatr
getatr


The following Part events have been added to VisualAge RPG.
Part Event Description
Graph Popup New event added
Notebook Page SelPending This event is signalled for the current page when a user clicks on another page. For example, the action subroutine for this event can check that all required input has been entered. If not, return "NODEFAULT" so the VARPG runtime engine won't switch to another page. This removes the need to disable other pages or make them invisible. An example of the code follows:
 C     NBP_1         BEGACT    SELPENDING    FRA_1
 C                   if        %getatr('FRA_1':'cusno':'text')=*blank
 C     *msg0001      dsply                   rc1               9 0      Display an error message;
 C                   eval      RC='*NODEFAULT  '
 C                   else
 C                   eval      RC='*DEFAULT    '
 C                   endif
 C                   ENDACT    RC

WebSphere Studio for iSeries

For information about prerequisite information and limitations specific to the IBM WebSphere Studio for iSeries, please refer to the WebSphere Studio README and ReadMe 3.5 FixPack 2 files. These notes can be viewed from the Windows Start Menu by selecting Programs> IBM WebSphere Development Tools for iSeries> IBM WebSphere Studio for iSeries.

About BiDi Support
Each DTC in WebSphere Studio for iSeries now has a directionality attribute property that specifies direction of text. This property is in the General page of the control properties. The choices are:
LTRText direction is Left to Right
RTLText direction is Right to Left
NONEText direction is the default for the language

In addition, Subfile also has the 'directionality' attribute for each field under the'Fields Properties' page. The 'directionality' attribute under 'General' property page of Subfile defines how the columns/fields are arranged. The 'directionality' attribute under 'Fields Properties' property page defines how the text of the field is rendered.

In the Program Call Definition page of the Web Interactions Wizard, a new attribute bidistringtype, has been added. The choices are described below.
String Type Type of
text
Orientation Symmetric
swapping
Numeral
shape
Text
shapes
Default The default string type for non BiDi data (LTR)
ST4 Visual LTR No Nominal Shaped
ST5 Implicit LTR Yes Nominal Nominal
ST6 Implicit RTL Yes Nominal Nominal
ST7 Visual Contextual LTR No Nominal Nominal
ST8 Visual RTL No Nominal Shaped
ST9 Visual RTL Yes Nominal Shaped
ST10 Implicit Contextual LTR Yes Nominal Nominal
ST11 Implicit Contextual LTR Yes Nominal Nominal
Note: Each CCSID has a default CDRA string type which defines a set of BiDi flags. When using these constants while performing conversions on BiDi strings, the parameter string type should always be either ST5 (LTR), ST6 (RTL), ST10 (Contextual LTR), or ST11 (Contextual RTL).

About two new fields
The first page of the Publishing Wizard has two new fields, WAS application server name and WAS servlet engine name. They have default values Wdt400AppServer and Wdt400ServletEngine that were previously hard coded.

About a field label change
The first page of the Publishing Wizard has a field labeled WAS Node name that was previously labeled XML node name. When specifying the WAS node name in the publishing wizard, use the node name you see in the administrative console.

Distributed Debugger and Object Level Trace

For information about prerequisite information and limitations specific to the IBM Distributed Debugger and Object Level Trace, please refer to the IBM Distributed Debugger and Object Level Trace Release Notes. These release notes can be viewed from the Windows Start Menu by selecting Programs> IBM WebSphere Development Tools for iSeries> IBM Distributed Debugger> README.

Known Problems and Workarounds

JDK Notes
IBM's Java 2 Software Development Kit (J2SDK), Standard Edition v1.2.2 is included with this product. J2SDK includes JavaDocs. If you choose to use a different JDK, then it must be version 1.2 or higher to ensure the functionality of all pieces of Java code.

To use a different JDK, determine its JRE (Java Runtime Environment) home directory. In the CODE Editor, enter the command "SET GLOBAL.JREHOME x:\dir" where x:\dir is the JRE home directory. For example, "SET GLOBAL.JREHOME C:\JDK1.2\JRE".

If you plan to use the VisualAge RPG Media component, then install the Java Media Framework API.

VisualAge RPG GUI Designer and Java Plug-in
Netscape Navigator and Microsoft's Internet Explorer do not currently support the same level of the J2SDK that VisualAge RPG uses. Therefore, applets created with the VisualAge RPG GUI Designer will not run directly with these browsers. To run VisualAge RPG applets in either of these browsers, you must have the Java Plug-in 1.2 installed (included with J2SDK). You can download the J2SDK from The Source for Java Technology Web page site at java.sun.com.

VisualAge RPG IFS names
Always use IFS directory names that are 1 to 8 characters long and have no spaces.

Problems with Help
WebSphere Development Tools for iSeries uses the VisualAge Help System to deliver its online help information through your web browser. If you are having trouble launching, using, or searching the help, a problem solving document is available on the installation media. Put CD 1 or the DVD into its drive and use Windows Explorer to go to file x:\install\help\helpyyy\helpTroubleshooting.htm, where x is the drive letter, and yyy is your language code as shown below:
LanguageCodeLanguageCodeLanguageCodeLanguageCodeLanguageCode
German deu English enu Spanish esp French fre Italian ita
Japanesejpn Koreankor Portugese
(Brazilian)
bra Chinese
(Simplified)
chs Chinese
(Traditional)
cht
After installation, the troubleshooting document is located in the product directory install\help.

WebSphere Studio for iSeries: Invoking Subfile DTC API
The host service program, QGPL/QDTSSFL.SRVPGM, is required when the user host program needs to invoke the Websphere Studio for iSeries Subfile DTC API.

For Installation

  1. A host ID with *ALLOBJ and *SAVSYS authorities is required for the installation steps.
  2. Transfer the qdtssfl.sav savefile from your workstation to iSeries host QGPL library:
    1. Open a command prompt window
    2. Change to the source directory of qdtssdfl.sav, x:\WDT400\Studio35\Affinity where x:\WDT400 is the installation drive and directory of the product
    3. Enter these commands:
      ftp iSeriesHost
      cd QGPL
      binary
      put qdtssfl.sav QDTSSFL (assuming the QDTSSFL SAVFILE has been created, e.g. CRTSAVF FILE(QGPL/QDTSSFL))
  3. Restore the QDTSSFL SRVPGM to QGPL library from the savefile:
    RSTOBJ OBJ(*ALL) SAVLIB(QGPL) DEV(*SAVF) SAVF(QGPL/QDTSSFL) RSTLIB(QGPL)

For Development environment

  1. Ensure the QGPL library is in the library list.
  2. Bind the user program that makes the Subfile DTC API call to QGPL\QDTSSFL.SRVPGM

For Runtime environment, ensure the QGPL library is in the library list.

Notes for pre-V5.1 users:

  1. All existing programs that are bound to the QSYS\QDTSSFL.SRVPGM have to be rebound to the new QGPL\QDTSSFL.SRVPGM.
  2. After all the existing programs mentioned above have been rebound to the new SRVPGM, it is safe to remove the pre-V5.1 version of QDTSSFL.SRVPGM in QSYS library.

Using samples from Enterprise Toolkit for iSeries
In order to use samples provided in ET/400, you must restore the ADTSLAB library. For WebSphere Development Studio for iSeries V5R1, this library is located in QPDA.

Truncated Display Messages in CODE
Long messages in CODE Editor are sometimes truncated. Select the message and click Help or press F1 to see the entire message.

Browser Problems

Certain components of WebSphere Development Tools require Internet Explorer as browser (see Software Requirements in Release Notes). Some Netscape problems are described below. Use Internet Explorer as your default browser to avoid these constraints and problems.

Netscape Search in Windows 2000
There is a known problem with Netscape (versions 4.5 to 4.74 and possibly others) on some Windows 2000 machines that may make searching the online help extremely slow. When you submit a form from these versions of Netscape, the Netscape application uses most available processor cycles on your machine until a response is received from the remote system. This is not normally a problem when doing a remote search (e.g. on a website). However, because the product's search program is running on your own local machine, the fact that Netscape takes so much CPU time means that there is very little CPU time left over for the search program to perform its search. As a result, a search action that should return a result within a second may take several minutes on Windows 2000.

You can avoid this performance problem by selecting a different, non-Netscape window after each time you submit a search. This typically causes Netscape to stop using excessive CPU cycles while waiting for a response and search results are usually displayed within a second after doing this window switch.

Alternatively, you can use Microsoft Internet Explorer to view the help. The performance problem does not occur with this browser.

Netscape Navigator non-conformance
Netscape Navigator does not conform to standards for HTML 4. Web pages generated from WebSphere Studio for AS/400 and displayed by Netscape Navigator have DTC problems described in the following table. These problems do not occur when Internet Explorer is used.

DTC type Appearance problems Events problems Attribute problems
Entryfield Color and Background color defaults cannot be overridden. OnSelect, OnClick, OnDblClick, OnMouseOver, OnMouseDown, OnMouseUp, and OnMouseOut are not supported. The "alignment" attribute moves the entire field, not just the text.
The "readonly" attribute is not supported, but this problem can be fixed as follows:
- select the DTC
- display the Control Properties dialog box
- select the Event tab
- click the onFocus event
- enter "this.blur();" into the script box.
Check box No problems OnChange is not supported. No problems
Combobox Color and Background color defaults cannot be overridden.
Font is ignored.
No problems No problems
Listbox Color and Background color defaults cannot be overridden.
Font is ignored.
No problems No problems
MLE Color and Background color defaults cannot be overridden.
Font is ignored.
Text incorrectly wraps to next line.
OnSelect is not supported. No problems
Pushbutton Background color always appears as light grey. OnKeyPress, OnKeyUp, OnKeyDown, OnMouseOut, and OnMouseOver are not supported. No problems
Radiobutton No problems OnMouseOut, OnMouseOver, OnKeyUp, OnKeyDown, OnKeyPress, and OnChange are not supported. No problems

Internet Explorer and help for AS/400 Toolbox for Java
Some Toolbox for Java help pages do not use the correct character set when displayed with Internet Explorer. The correct character sets for each language are:
Language Name of character set
Simplified Chinese Chinese Simplified(GB2312)
Traditional Chinese Chinese Traditional(Big5)
Korean Korean
Japanese Japanese(Shift-JIS)

Use these steps in the browser window to select the correct character set for your language.
  1. Click View on the menu bar to open a drop down list.
  2. Put the cursor over Encoding to open a list of character sets.
    1. If the required character set is on this list, click on it.
    2. If the required character set is not listed, put the cursor over More to open a longer list of character sets.
    3. Click the required character set.
This must be done each time a help page is opened with an incorrect character set.

The Distributed Debugger
When you are debugging a Program or Service Program that was launched from a Web page generated by the WebSphere Studio for AS/400, Program completion or Service Program entry point completion does not cause the debugger to terminate. This prevents subsequent debug sessions. To be able to debug again, use the Halt button to close the outstanding debug session.

Object Level Trace
If Object Level Trace on Windows 95 or Windows 98 does not start, make sure that your environment space is set to the maximum value. In your CONFIG.SYS find the SHELL directive and make sure that the /E value is set to 32768. For example: SHELL=C:\WINDOWS\COMMAND.COM /p /E:32768

The OLT viewer will fail if environment files in directory DbgProf are corrupted. If this happens, delete all files in the DbgProf directory. There is a separate directory for each user. When the OLT viewer starts, it will create the files again.

The OLT viewer displays the error "Cannot open input stream for dertrdfl." when it is started the first time or after environment files in directory DbgProf are deleted. This error does not affect how the OLT viewer performs.

Norton AntiVirus
If Norton AntiVirus is installed on a Windows 98 machine and any parts of WebSphere Development Tools, such as Debugger or Object Level Trace, do not function, then disable Norton Antivirus and try again.

Other Sources of Information

Visit our World Wide Web pages at:

ibm.com/software/awdtools/wdt400/ Click Support, then select an item under Support Downloads for Web Updates

You can also get to these pages by following the links from the IBM Software home page ibm.com/software/

The Redpaper REDP0503 provides a excellent overview of this product. Go to the Redbooks site, click Redpapers in the left frame and click the title "IBM WebSphere Development Tools for AS/400: An Introduction". You will see an abstract of the document. Click View Online to read a PDF version of the paper.

Follow the newsgroups and post your questions:

News server:

news.software.ibm.com

Suggested newsgroups:

ibm.software.code400

ibm.software.vajava

ibm.software.varpg

ibm.software.websphere.studio400


How to find your License Agreement

License Agreement files for this product are in the subdirectory license in the root product directory.

Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

Director of Licensing
Intellectual Property & Licensing
International Business Machines Corporation
North Castle Drive, MD - NC119
Armonk, New York 10504-1785
U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Canada Ltd.
Department 071
1150 Eglinton Avenue East
Toronto, Ontario M3C 1H7
Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Programming Interface Information

This documentation describes General-Use Programming Interface and Associated Guidance Information provided by IBM WebSphere Development Tools for iSeries.

Trademarks and Service Marks

The following terms are trademarks or registered trademarks of the International Business Machines Corporation in the United States or other countries or both:
  • AIX
  • AIXwindows
  • AS/400
  • AS/400e
  • IBM
  • Integrated Language Environment
  • iSeries
  • Operating System/400
  • OS/400
  • RPG/400
  • VisualAge
  • WebSphere

InstallShield is a trademark of InstallShield Corporation.

Intel and Pentium are registered trademarks of Intel Corporation.

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

Netscape Navigator is a trademark of Netscape Communications Corporation.

ActiveX, Microsoft, SourceSafe, Visual C++, Visual SourceSafe, Windows, Windows NT, Win32, Win32s and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.