Enterprise Connector for CICS
Version 6.0
Release Notes
Updated June 19, 2000
- Summary
- Installation and Configuration
- Exception Management and Logging
- Tracing the Enterprise Connector
- Documentation
- Known Problems
These release notes detail the known problems and changes for the iPlanet Application Server Enterprise Connector 6.0 for CICS.
The Enterprise Connector for CICS supports OS/390 MVS 5.22, CICS 3.2, and TCP/IP 3.1 and above with current APARS.
This enterprise connector has the following platform and system requirements:
Supported Platforms
Vendor |
Platform |
Microsoft |
Windows NT 4.0 Service Pack 5 |
Sun Microsystems |
Solaris 2.6 |
System Requirements
Installation and Configuration
iPlanet Application Server 6.0 components and the Unified Integration Framework (UIF) must already be installed on the server machine. Installation of CICS requires two phases:
1. Install the CICS enterprise connector on the application server machine.
- for NT, run setup.exe in the inscics directory
- for Solaris, untar the file and execute setup in the inscics directory from the command line
2. Install mainframe components on the mainframe.
- locate the mainframe components in the directory:<youriASdirectory>/ias/APPS/adapters/cics/backend
- follow instructions provided in the Mainframe Component Installation in the Administrator's Guide
Note: After installation on Windows NT, the machine must be manually restarted.
Exception Management and Logging
The exception and logging mechanism provides the following functionality:
- writes messages into default iPlanet Application Server log.
- enables the administrator to switch between varying logging levels at runtime.
Only one generic Unified Integration Framework (UIF) exception message is ever thrown. The exception messages that are thrown relate to data object APIs or enterprise connector errors. The programmer does not have to handle exceptions, since the BspException extends java.lang.RuntimeException. The application programmer can safely skip writing special error-handling code.
Tracing the Enterprise Connector
The CICS.ini file contains the variable SRVND_DBG=FALSE.
The CICS.ini file must be in the same directory where the services, kcs, kjs, and so on, are started: <root>\iPlanet\server4\ias
To activate the trace file for the adapter, set the variable SRVND_DBG=TRUE. The file CICS.log is then created.
Documentation
The Administrator's Guide and Developer's Guide are included with the product.
Adobe Acrobat 4.0 and PostScript printer with PS level 2 fonts are required to print the PDF version.
Note: The documentation shipped with this product has been updated. Please download current documentation from:
http://docs.iplanet.com/docs/manuals/ias/60/CICS/admin/contents.htm for Administrator's Guide
http://docs.iplanet.com/docs/manuals/ias/60/CICS/dev/contents.htm for Developer's Guide
Known Problems
CICS Related Problems
Adapter Crash on Solaris
Any iPlanet Application Server kjs process using the CICS datasource is liable to crash under load due to network problems or the relay being down or interrupted. Check if the relay program is up and reachable.
Array Element Type Enforcement
Arrays are used to store elements of the same type; however, homogeneity is only enforced when using the addElem( ) method to add elements to arrays. Use the addElem( ) method and not methods in the IUIFDataObjectList interface, to add elements to arrays.
Correct Conversation Type Value Must Be DIRECT in iAS APPC Protocol.
createInstance( )
The createInstance() method creates an instance of an IBSPDataObject object (not an instance of IBSPDataObjectInfo).
Log File Too Large
The CICS adapter's data source XML file (sample, as well as template) should set the pooling debugLevel=0. The administrator can change this level using kregedit if more information is needed.
Management Console Icon Not Appearing on NT
If "\" is found at the end of the path in the auto.ext file when typing %PATH%, add a ";" after it.
Management Console Must Be Restarted
After creating a new data source or editing an existing data source, the CICS Management Console must be restarted.
Solaris Installer
When write access to certain files, which the Solaris installer creates in the /tmp directory is denied, the Solaris installer fails. The files in /tmp are:
- import_adapterdatasource_sh
- import_adaptertype
- appltab
- ecuplugin
- ldapmodify_sh
- datasource
- import_uif_sh
- UifConfig.properties
- run.sh
- install.ini
To resolve this change user to root and manually remove the files from /tmp.
Solaris Installer Not Recognizing the Application Server
If iAS is not installed under the specified server root directory and only iAS for CICS 6.0 is being installed, the following error message will display: "ERROR: UIF depends on iPlanet Server Family Core Components to be installed. Select iPlanet Server Family Core Components. Press any key to continue." Enter CTRL B twice to go back to two previous screens.
StringMaxLen
Page 118 should read FStringMaxLen, not GetElemStringMaxLen.
Syntax Error Converting Datetime from Character String
The updateRow function does not allow updating date in Java.sql.Date format against a MSSQL server.
TelcoSample Can't Find Starting Page
When running the TelcoSample project from iPlanet Application Builder, the starting page cannot be found. Fix this by adding the following lines to the .gxm file and recompiling the project:
TreeLevel=0
Filename=index.html
IsDir=false
FileType=HTML Page
Source=http
RelToSrcPath=cicsSamples/index.html
Destination=http
RelToDestPath=cicsSamples/index.html
UIF (BSP) Related Problems
BSPException : Error in GetPooledData: RC:00 in Telco Customer Services Sample
The installation guide contains a separate section describing the required steps to install the telco samples. It involves creation of a DB2 database, and creating a plan and packages that access that database. Make sure that the CICS where the telco samples are running has a DB2 attachment facility installed. Verify that COBOL language environment is installed there as well.
BSPException: This Service Provider Object Instance Not Valid
The CICS connector couldn't be loaded during installation. To workabout, create a directory:
/local/moti/ias6cics_adaptersdk/lib/uif.
Then copy to it:
your_nas_server_root/ias/APPS/bin/libUIF_ext.so.
For OS2.6 use linker patch version:
-rwxr-xr-x 1bin bin 166196 Mar 24 1999 ld.so.1.
DataObjects Cannot Be Shared
The Java API must not be used in such a manner that two dataobjects end up sharing the same dataobject (or some such restriction).
DataObject Is Not Thread Safe
Only sharing of read-only objects, such as DataObjectInfo, is supported.
DataObjectMgr Interface
The statement on Page 88 "DataObjectMgr implements methods for creating data objects" is NOT correct. This statement should be removed, as the subsequent API Listing indicates.
dumpDataObject Method Only Dumps to Screen
IBSPDataObject.createDumpToOutputStreamVisitor (OutputStream os) has been added to allow dumping to any output stream, including an output stream on a file.
Duplicate Repository Nodes
Duplicate repository nodes are not allowed; however, this restriction is not enforced. Duplicate node cause unpredictable behavior of the Repository Browser; for example, the browser may not refresh properly. XML files containing a duplicate node may generate errors. Correct the error and reimport.
Directory Server Hostname Prompt in Solaris Installer
While installing on Solaris, the installer prompt: Enter the Directory Server Identifier, should be changed to: Enter the Directory Server Host Name.
Exception Message rc=5
When choosing "DISPLAY" on "To Start PhoneBookDemo" this message indicates the backend not installed properly.
Failed to Create Data Connection with Specified Drivers
Database clients (Sybase /Oracle /Informix)can only be installed by a user with Admin privileges.
Get Remote File
When converting COBOL to XML from a remote machine these fields must be filled in. Enter host name, name of current user, current system password, starting point of COBOL files, and local directory where files will be saved. Click OK, then select a file or files to convert from the mainframe tree view on the FTP Chooser window. Clicking on a "+" will allow you to view partitioned dataset.
Hierarchy of DataObjectExceptions Has Been Added
HTTP Port Missing in Sample URL
The Program menu link to the Samples page assumes the web server is running on standard http port 80. If this is not the case, the link fails. Manually insert the port number in the URL location on the web browser and the page appears.
IBSPDataObject.equals( )Method Has Been Added
This method allows comparison of two IBSPDataObjects.
UIF Access Interrupted
Running GX.Release( ) on IBSPRuntime object, in 6.0 CICS for iAS, interrupts access to UIF. Do not run GX.Release ( ) on an IBSPRuntime object.
UIF Runtime Connection Pool Exhausted
Applications must call disable( ) on an IBSPServiceProvider before exiting an EJB or servlet. If disable( ) is not called, the CICS transaction stays alive until it is timed out, possibly exhausting the connection pool.
Use GX.Release( ) for Freelist Advantage
For freelists to be effective, the servlet /EJB should do a GX.Release(obj) on any object returned by the UIF API as soon as it finishes with it, and before exiting the EJB /servlet. This will return dataobjects to freelists and avoid unnecessary object creation under peak load. The following programming constructs are not recommended, since they implicitly create wrapped java objects, which can only be gc'd and not GX.Release:method chaining:
((IBSPDataObjectStructure)datablock.getDataObject("X")).getAttrString("Y")
and local vars implicitly going out of scope. A local var must be explicitly GX.Released before it goes out of scope.
Copyright © 2000, Sun Microsystems Inc. All rights reserved.