iAS Enterprise Connector for CICS

Version 6.0 Service Pack 1

Release Notes

Updated January 17, 2001

Contents

Summary

The release notes detail the changes, resolved issues and known problems for iPlanet Application Server Enterprise Connector for CICS, Version 6.0 SP1 release.

System Requirements


The following table lists the hardware and software requirements for installing and running the CICS Enterprise Connector.
 
Component Requirement
Computer and Operating System One of the following systems:

• Intel Pentium microprocessor running Microsoft Windows NT version 4.0 with Service Pack 5

• Sun SPARC running Solaris 2.6 or Solaris 8.
Memory Per CPU: 256 MB minimum; 512 MB recommended.
Available disk space Total disk space: 200 MB on NT, 400 MB on Solaris.
CD-ROM drive CD-ROM drive.
Network software TCP/IP or SNA/APPC for NT.
Browser software One of the following web browsers:
• Netscape Communicator 4.5
• Microsoft Internet Explorer 4.0 (NT only)
CICS  System IBM CICS running on OS/390. The required releases are MVS 5.2.2 and CICS ESA 4.1 and above with current APARS.
iPlanet Application Server Enterprise Connector for CICS includes installation and configuration for both TCP/IP and SNA (APPC) protocols.
Other software • iPlanet Application Server 6.0 SP1
• Unified Integration Framework 6.0 SP1

The iPlanet Application Server and Unified Integration Framework must be installed prior to installing the CICS Enterprise Connector.

Installation

Please make sure all iPlanet Application Server 6.0 SP1 components and the Unified Integration Framework (UIF) SP1 have already been installed on the server machine. The iPlanet Application Server Enterprise Connector for CICS must be installed on the same machine as the iPlanet Application Server.

You also received a second CD containing the open source ICU libraries, used for character set translation.

Installation

Installation of this product is as follows: Post Installation Issues

1. ICU libraries


To complete the setup for the CICS Enterprise Connector, you must install the ICU  libraries. Before proceeding to copy the ICU libraries, you must read and accept  the ICU license agreement present in the ibm_icu_license.html file on the ICU CD.

Installation of ICU is as follows:

For NT:

Uncompress the icu-NT.zip under the <iAS InstallDir>\ias\APPS\bin directory.
This places the following files/directories under the  <iAS InstallDir>\ias\APPS\bin directory:

For Solaris:

Uncompress the icu-SOLARIS.tar under the <iAS InstallDir>/ias/APPS/bin directory.
This places the following files/directories under the  <iAS InstallDir>/ias/APPS/bin directory:

2.  UIF User Mapping Patch

The following UIF User Mapping Patch must be applied:

For NT:

  1. Down load "cBSPUserMap.dll" .
  2. Copy the patch file cBSPUserMap.dll to the directory <iplanet directory>\ias\APPS\bin.
For Solaris:
  1. Down load "libcBSPUserMap.so".
  2. Copy the patch file libcBSPUserMap.so to the directory <iplanet directory>/ias/APPS/bin.

Upgrading From the Enterprise Connector for CICS Version 6.0

Due to changes in the repository structure to support internationalization (I18N), you need to recreate all the CICS datasources after installing the UIF and the CICS connector. You also need to perform datamining after you recreate the datasources.  All user mapping information is overwritten, however, you may backup user mapping information for a given datasource from the previous version and use it in this release.

The procedure for backing up and re-using user mapping information is as follows:

  1. Before installing the UIF v6.0 SP1, backup the ENTIITY_MAPPINGS nodes from each CICS Datasource in the UIF repository, using the Repository Browser's export utility ( for example, DS1userbackup.xml DS2userbackup.xml... ).
  2. During UIF installation, the installer prompts you to overwrite the existing BSP node. Select YES to overwrite the existing BSP node.
  3. For NT:Copy the repository.dtd file from the <iasinstalldir>\ias\APPS\adapters\cics\samples\metdata directory to the directory where the saved XMLs are stored. For Solaris:Copy the repository.dtd file from the <iasinstalldir>/ias/APPS/adapters/cics/samples/metdata directory to the directory where the saved XMLs are stored.
  4. Import the DS1user.xml using the Repository Browser's import utility under the corresponding DataSource DS1.

National Language Support

The iPlanet Application Server Enterprise Connector for CICS provides full support for building applications that use the prevalent and popular mainframe character sets. You need to set both the client character set and the backend character set to work with other languages.

To set the client character set:

In the servlet, call GX.setCharSet with the client character set.

To modify the backend character set:

Enter the backend character set in the Backend Character Set Field in the Create or Edit Data Source dialog boxes.
The connector converts the data from the client character set to the backend character set. Note, the client and backend character sets must be compatible.
 


 

Running the Sample PhoneBookDemo in i18n mode

The following tip can be applied to run the samples on a mainframe that is using a character set other than IBM-1047.
The tip below refers specifically to Japanese however, it may also apply to other languages.

The Sample Application must be modified to run in i18n mode.
For example, modify PhoneBookServlet.java by adding the following code:

          com.kivasoft.util.GX.SetCharset("Shift_JIS");

Refer to iPlanet Application Server Guides for i18n Application Development .

Documentation

This product includes an Administrator's and a Developer's Guide. The installer copies these publications to the ias/APPS/docs/cics sub directory of the root installation directory of your iPlanet Application Server. These documents are available online in PDF and HTML formats. To locate these files, use the following URL:

http://docs.iplanet.com/docs/manuals/ias.html

Adobe Acrobat 4.0 and PostScript printer with PS level 2 fonts are required to print the PDF version.

The following lists corrections to the documentation posted on the web site.

ENTITY MAPPING

You must create at least one entity and one user after creating a new data source.

DATA MINING -  GENERATING A HINTS FILE

In Chapter 4, "The Management Console", in the section To Choose a Cobol File (local), if you select to generate a "hints" file, please replace step 3 with the following text:

3. Click Yes to generate a hints file for the compiler or No.
The hints file lists the structure that will be used in the input and output nodes in the the repository. If you select Yes, the selected file is displayed in the Management Console Hints Generator Window.

4.Go to the Linkage Section in the file and highlight the structure you want as input. 
In the example above, inputoutput-sec represents the structure of the input and output structures with the respective fields. The input and output structures may be in different sections.

5. Select Tools and then select Add Input Parameter as shown in the following display.
The name of the structure you selected is displayed in the Input Parameters box at the bottom left of the display.

6. Go to the Linkage Section in the file and highlight the structure you want as output. 

In the example above, inputoutput-sec represents the structure of the input and output structures with the respective fields. The input and output structures may be in different sections.

7. Select Tools and then select Add Output Parameter as shown in the following display.
The name of the structure you selected is displayed in the Output Parameters box at the bottom right of the display.

8. Select File and then select Generate Hints.
An Information Box is displayed indicating that the hints file was generated successfully.

9. Click OK.
The Choose Data Source Window is displayed.

10. Select a data source and click OK

The COBOL file is converted to XML and loaded into the repository.

Resolved Issues

The following issues have been resolved in the iPlanet Application Server Enterprise Connector for CICS 6.0 Service Pack 1 release.
Summary
Exceptions now contain the backend error code. 
An entity can not be deleted if there are mapped users.
Internationalization (I18N) support. CICS  National Language Support is included in the iPlanet Application Server Enterprise Connector for CICS SP1. 
A screen has been added at the end of the procedure for creating a new data source using the Management Console. The new screen will alert the user if there is an existing data source with the same name and ask, Yes or No, if the existing data source should be over-written. If you choose the Yes option, the data source will be over-written; if you choose No, the data source that you created will be deleted.
You do not have to restart the Management Console after editing a data source.
A Refresh button was added to the Repository Browser that allows the user to refresh the repository without closing the repository and re-activating.
Support for long data type has been added.

Known Problems

ID:517183

Uninstaller Removes Common Files in Multi-connector Installation

When uninstalling one of several connectors, such as R/3, PeopleSoft, or CICS, the common directories /ias/APPS/console and /ias/APPS/ecu may be deleted. It is necessary to copy these directories back to APPS directory from /ias/APPS/UIFbackup for the CICS  connector to function correctly.

To Uninstall a Connector on NT

If you want to uninstall a connector from an NT machine that has more than one connector installed, perform the following tasks.

1. Uninstall the connector. Refer to Chapter 2 in the Administrator's Guide.

During the uninstallation procedure the connector files shown in the right panel, as seen in the screen capture below, are removed from the iPlanet/iAS6/ias directory and moved to the UIFbackup/console directory. The connector files need to be copied back to their original location.

2. Copy the console specific directories, the top level directory and the connector specific directories to the ias/Apps/console for the following folders:

3. All the other directories, with all their included files, and the LocalDebug.class should be copied back.

4. Copy the following connector files to the console directory: Appltab and ldobuffer.dll.

Uninstalling Connectors on Solaris

If you want to uninstall a connector from a Solaris machine that has more than one connector installed, perform the following tasks.

1. Uninstall the connector. Refer to Chapter 2 in the Administrator's Guide.

During the uninstallation procedure the connector files are removed from the iPlanet/iAS6/ias directory and moved to the UIFbackup/console directory. The connector files need to be copied back to their original loacation.

2. Copy the console specific directories, the top level directory and the connector specific directories to the ias/APPS/console for the following folders:

3. All the other directories, with all their included files, and the LocalDebug.class should be copied back.

Servlet Limitation

The number of characters in any field must not be greater than the field length as defined in the repository.When writing a servlet the programmer must check the field length of the input data using either the repository browser or the data object API. If the length of the input is greater than the field length, the programmer must ensure that the program throws an exception.
 

Missing File for the Enterprise Connector for CICS

The PHONBOOJ program is missing from the build library. The file phonbooj.xmt (mainframe binary file) is attached.  Detach the file,
save it to disk, and then "FTP'  it  to the mainframe.

 phonbooj.xmt

To Copy the PHONBOOJ program into the iPlanet Application Server CICS Load Library:

1. Allocate a dataset on MVS with the following attributes:

LRECL=80, RECFM=FM, DSORG=PS,BLKSIZE=3120
Name it 'IAS.PHONBOOJ'

2. Perform a binary FTP of the attached file to IAS.PHONBOOJ .

3. Issue the following TSO command:

RECEIVE INDATASET('IAS.PHONBOOJ')

The following prompt is displayed:

INMR901I Dataset IAS.I4C.REL600.CICS.LOAD from MIKE on NODENAME
INMR902I Members: PHONBOOJ
INMR906A Enter restore parameters or 'DELETE' or 'END' +

4. Enter:

DATASET(IAS.CICS.LOAD)

where IAS.CICS.LOAD is the name of the CICS load library for iAS

Copyright © 2000, Sun Microsystems Inc. All rights reserved.