************************************************************************
* IBM CICS Universal Client for Windows NT - README             v3.1.2 *
************************************************************************

Welcome to the IBM CICS Universal Client ...

This file contains important information about the IBM CICS Universal
Client for Windows NT that may not be available in the printed
documentation.

Summary of Topics
=================
- Installation Issues
  - Java Runtime Environment
  - Adobe Acrobat Reader
  - TCP62 Support shipped with the Client
  - TCP62 Support from IBM Personal Communications
  - TCP62 Restriction when Client running as a Service
  - Using Windows credentials for security
- CICSTERM behaviour and Signon Capable Terminals
  /****************************************************************************/
  /* WARNING: The default CICSTERM behaviour changed in release 3.1 and later */
  /*          See below for details.                                          */
  /****************************************************************************/
  - CICS TS v1.3 Servers
  - TX Series Servers
  - Security on OS/390 Servers
- EPI Purge Terminal Restriction
- Timeout processing on TCP/IP protocol
- C++ Class libraries for IBM VisualAge C++ for Intel Platforms
  - Migration issues
- DBCS Support in the COM and C++ Libraries
- Update to Client/Server Programming Book
- Updates to C++ and COM Automation programming books
  - Disconnect Documentation
  - exObject method in CclException Class
  - CICS Client COM objects and Apartments
- Maximum Requests
- Windowed alternative to CICSCLI.exe
- Tracing enhancements
- Service and Updates
- Giving feedback


Installation Issues
===================
Java Runtime Environment
------------------------
The Java Runtime Environment is required to run the GUI configuration
tool (ctgcfg). Version 1.1.8 is recommended. See http://www.ibm.com/java
for details. If you do not wish to install a Java Runtime Environment
follow the steps below:

On installation:
1. When the install Java panel is shown, select 'No, I have an existing JVM'
2. On the Select JVM panel, select the option 'Enter the path to another
   java environment'
3. On the next panel, make sure the Java Path field is empty.

If you install a JVM at a later date and you then wish to use ctgcfg, you must
first use the command ctgjava to set the location of where the JVM is installed.
Note, JDK 1.2.2 is supported, but not Java 3.

If this product has been supplied on CD the Java Runtime Environment is
included. It can be found in the directory JRE\Windows with the filename
ibm-jre-n118p-win32-x86.exe. To install:
1. Run the program:  ibm-jre-n118p-win32-x86.exe

Adobe Acrobat Reader
--------------------
If this product has been supplied on CD the English Adobe Acrobat Reader
is included. It can be found in the directory Acrobat\Windows with the
filename rs40eng.exe. To install:
1. Run the command: rs40eng.exe

TCP62 Support shipped with the Client
-------------------------------------
The TCP62 support shipped with the CICS Universal Client is not itself a
component of the Client install, it is a separately installed package.
TCP62 does not therefore appear in the "Component List" of the Client install
and so can not be added or removed as other components can. If you wish to
add or remove TCP62 support at a later date, you must run SETUP.EXE
located in the TCP62 directory of the Client install image.

A new version of TCP62 is included. It is functionally equivalent to the TCP62
part of Personal Communications version 5.0 plus a fixes for Running as a
Service and Silent Installaton.

TCP62 Support from IBM Personal Communications
----------------------------------------------
If you are using IBM Personal Communications for NT (PComm) version 4.2,
it must be at CSD 5 level or above. For version 4.3, CSD 2 or above is required.

To use the TCP62 protocol with PComm, you must install the PComm AnyNet support.
If you have not done so, you will get an error that TN62API.DLL cannot be found
when trying to use the TCP62 protocol.

TCP62 Restriction when Client running as a Service
--------------------------------------------------
If you install the Client as a service and install TCP62. TCP62 will run as a
service. If you install TCP62 at a later date you will need to do the following
to enable it to run as a service:

1. start regedit
2. Go the following registry key
   HKEY_LOCAL_MACHINE\SOFTWARE\IBM\Personal Communications\CurrentVersion\NODE_CONFIG
3. Create a new DWORD value with the following details:
   name = StartOnBoot
   data = 2

IBM Personal Communications will not currently run as a Service.

Using Windows credentials for security
--------------------------------------
If you wish to use to use this feature, you must do the following.
1. Change to the directory:
   \Program Files\Common Files\IBM\IBM Integrated Sign ON
2. Type bthdinst -i CICSCLI
3. Reboot

Warning: When uninstalling you MUST uninstall in the following sequence:
1. Change to the directory:
   \Program Files\Common Files\IBM\IBM Integrated Sign ON
2. Type bthdinst -u CICSCLI
3. Reboot
4. Uninstall the client as normal


CICSTERM behaviour and Signon Capable Terminals
===============================================
CICSTERM now attempts to install a signon capable terminal by default.

Use the option '-a' to request the default CICSTERM behaviour as in
releases prior to v3.1.0.

CICS Servers require APAR fixes to support the terminal signon capability
function available in this release:

  CICS/ESA 4.1                        PQ30167
  CICS TS for OS/390 v1.2 and v 1.3   PQ30168
  CICS TS for VSE/ESA v1.1            PQ30170
  TX Series                           IY03691

CICS TS for OS/390 v1.3 Servers
-------------------------------
If the server does not have the required APAR applied and the '-a' option
is not specified on CICSTERM, the installed terminal will give unpredictable
results.

TX Series Servers
-----------------
If the server does not have the required APAR applied and the '-a' option
is not specified on CICSTERM, the Client will display the message:
    CCL7053E Errors found while communicating with server
and the message:
    CCL3105 Inbound CICS datastream error (CTIN, 4, 0)
will be written to CICSCLI.LOG.

On the server, the message:
    ERZ042004E/0112: An invalid request was received from client
will be written to CSMT.out and console.msg will include:
    ERZ014016E/0036: Transaction CTIN Abend A42B

Security on OS/390 Servers
--------------------------
Security checking done in the server for transactions started at a signon
capable terminal installed by a Client application does not depend on what is
specified by the ATTACHSEC option for the connection representing the Client.
Instead security checking depends on whether the user signs on while using the
terminal.

If the user does not sign on, the Client installed terminal is associated with
the default user defined for the server in the SIT. When a transaction is run,
the security checks are carried out against this default user. A check is also
done against the userid associated with the connection to see whether
the Client itself has authority to access the resource.

When a user does sign on, the terminal is associated with the userid just
authenticated. For transactions attempting to access resources, security
checking is done against the userid associated with the connection and the
signed-on user's userid.

It is recommended that the Usedfltuser parameter on the server connection
definition is set to Yes if using signon capable terminals and to No if using
signon incapable terminals.


EPI Purge Terminal Restriction
==============================
The EPI purge terminal function will not cancel ATI requests queued
against the terminal. This is a temporary restriction.


Timeout processing on TCP/IP protocol
=====================================
Client timeout processing will only result in server cleanup processing
on a server linked via the TCP/IP protocol, if the server has support
for this function installed.


C++ Class libraries for IBM VisualAge C++ for Intel Platforms
=============================================================
The CICS client C++ Class libraries for IBM VisualAge C++ and IBM C/C++
Compilers (CCLICW32.DLL) has been built using IBM VisualAge C++ V3.5 with the
runtime libraries dynamically linked. If you are building your application
using IBM VisualAge C++ v3.5 then these libraries can be used as is. (Please
note the requirements for runtime distribution as described in the IBM
VisualAge C++ documentation or C/C++ Compilers documentation).
If however you are using IBM VisualAge C++ V4.0 or IBM C/C++ Compilers V3.6
then before you can create and run your application you must first modify the
C++ class library using DLLRNAME to point to the current environment runtime
libraries.

The documentation that comes with IBM VisualAge C++ and IBM C/C++ Compilers
describes how to do this under the section
"Use DLLs and Executable Files Created in Previous VisualAge C++ Releases"
for IBM VisualAge C++ V4.0 and under the section
"Using Executable Modules from VisualAge for C++ Version 3.5 or Earlier"
for IBM C/C++ Compilers V3.6.

The Library CCLICW32.DLL is a multithreaded library, so if you wish to use
it with the IBM C/C++ Compilers V3.6 you need to issue the command:

   dllrname cclicw32.dll cppwm35i=cppymi36

and for IBM VisualAge C++ V4.0 you need to issue the command:

   dllrname cclicw32.dll cppwm35i=cppzmi40

(ensure you are in the directory where the file cclicw32.dll is before issuing
the above command).
When you come to distribute your application please refer to the requirements
as documented in the IBM VisualAge C++ documentation or C/C++ Compilers
Documentation.

Migration Issues
----------------
You cannot upgrade a client to version 3.1 or above and still have your C++
applications that use the CICS client Class libraries working straight away.
You will need to at least deliver the required IBM VisualAge C++ multithreaded
runtime library or the IBM C/C++ Compilers multithreaded runtime library
(conforming to the required restrictions as documented in the IBM VisualAge C++
or IBM C/C++ compilers documentation) and also you may need to modify the CICS
Client C++ Class library DLL as described above.


DBCS Support in the COM and C++ Libraries
=========================================
The COM and C++ libraries do not provide any specific support for 3270
datastreams that contain DBCS fields.


Update to Client/Server Programming Book
========================================
Additional return code on CICS_EpiTerminate:
   CICS_EPI_ERR_TTI_ACTIVE
       A transaction started from the EPI is still active or a
       CICS_EpiGetEvent call is still outstanding.


Updates to C++ and COM Automation programming books
===================================================

Disconnect Documentation
------------------------
There is a mistake in the CclTerminal Reference section, specifically in the
definition of disconnect. It should read as follows :-

disconnect (1)

     void disconnect()

     Disconnects the terminal from CICS. No attempt is made to purge any
     outstanding running transaction.

disconnect (2)

     void disconnect(Ccl::Bool withPurge)

     withPurge
           Ccl::Yes  -  Disconnects the terminal from CICS and will attempt
                        to purge any outstanding running transaction

           Ccl::No    - Disconnects the terminal from CICS. No attempt is
                        made to purge any outstanding running transaction.

In the COM Automation programming book the definitions of Disconnect and
DisconnectWithPurge are the same, this is not correct it should be

Disconnect
   Disconnects the terminal from CICS. No attempt is made to purge any
   outstanding running transaction.

DisconnectWithPurge
   Disconnects the terminal from CICS and will attempt to purge any
   outstanding running transaction

exObject method in CclException Class
-------------------------------------
This method is relevant to both ECI AND EPI.
exObject now will return the relevant CclTerminal object pointer in the
exception block for EPI applications. It will need to be cast to a CclTerminal*.
For example:
CclTerminal* pTerm = (CclFlow*)ex.exObject();

CICS Client COM Objects and Apartments
--------------------------------------
The design of the CICS client COM Libraries requires you to pass a COM
object to another COM object. For this to work you must ensure that the
relevant COM objects are created in the same apartment. For example in
ECI, for the link method call on the Connect COM object you pass a Flow,
Buffer and UOW object. These must all be created in the same apartment
in order to function properly. With EPI you need to ensure that the Terminal
Session and Map COM Objects are created in the same apartment. The Terminal
is responsible for creating the Screen object and it will create it in the
same apartment as itself. The Screen object is responsible for creating
field objects and creates them in the same apartment as itself.
The out-of-process servers guarantees that all objects are created in the
same apartment. You control the apartment where COM objects are created
when you use the in-process servers. In most cases in Visual Basic you
do not need to worry about apartments as you will be creating single threaded
applications.

Maximum Requests
================
The default value for 'MaxRequests' has been changed from 20 to 256. Note,
this number will need to be reduced if running to a CICS for OS/2 server,
over NetBios.


Windowed alternative to CICSCLI.exe
===================================
A new program, cicscliw.exe, has been added which provides identical functionality
to the standard cicscli program but which is a windows program that issues all of
its messages into a dialog box rather than the command prompt. This is only provided
for customers who want the same behaviour as the CICS Client for Windows 3.11 v2,
and unless this behaviour is required, the default cicscli.exe should continue to be
used.


Tracing enhancements
====================
There are two new command line switches on cicsftrc:
/s  Do summary trace formatting
/d  Do detailed trace formating

Summary trace formatting is driven from a text file (CCLSUMTR.TXT) which is
read in at initialization time. This defines the set of trace points we want
summary tracing for, and also what type of trace point it is. As DetailFormat
hits each trace point, if it is one of the ones read in from this file, a line
is generated in the summary file. This should be used as requested by Service.


Service and Updates
===================
Service and updates will be made available via the Internet.
See:
   http://www.software.ibm.com/ts/cics/support/details

APAR Fixes in v3.0.2
--------------------
PQ17866 ALLOCATE FAILURE HANGS EPI
PQ10841 TERMINAL CAN'T RECONNECT AFTER HOST IS CYCLED
PQ14864 MORE API INFORMATION IN TRACE
PQ16053 MISSING METHODS IN CCLEPI CLASS
PQ16369 MOVING DATA INTO LAST ATTRIBUTE CORRUPTS MAP
PQ16521 PROBLEMS WHEN USING ECI AND EPI TOGETHER
PQ16636 RECYCLING CLIENT CAN RESULT IN -5012 ERROR
PQ16971 EPI HANG WHEN TRACING ACTIVE
PQ17215 BAD CODEPAGE CONVERSION
PQ18131 ATI REQUESTS NOT INITIATED WITH C++ CLASSES
PQ19262 PASSWORD VISIBLE IN TRACE
PQ18357 NETWORK DELAYS CAUSE DCE RPC FAILURES
PQ17962 CICSTERM TERMINAL WINDOW HANG
PQ18267 ENABLEPOPUPS = N HAS NO EFFECT
PQ19523 EPIADDTERMINAL CAN SOMETIMES CAUSE EPI TO HANG
PQ19525 EPI CALLBACK ROUTINE MAY BE INCORRECTLY DRIVEN
PQ18445 LOOP IN EPIGETEVENT
PQ20250 C++ EPI CLASSES DO NOT BUILD FIELDS CORRECTLY

APAR Fixes in v3.0.3
--------------------
PQ22297 CICSPRNT CPU usage in background
PQ22301 CICSPRNT 1 print job per txn
PQ21189 Failure to reconnect over SNA session
PQ22831 SIGPIPE handle error
PQ22830 Variable retry interval parameter
PQ22426 Redesign to use pthread semaphores
PQ25017 Improvement of client security
PQ24339 Memory leak when server down
PQ21176 problem with lots of terminal deinstalls
PQ22983 CICSPRNT deals with file system errors incorrectly
PQ20693 PCOMM supplied with client upgraded to fixpack 2 level
PQ20313 ECI request to unavailable server may trap
PQ21147 Errors during shutdown of Win95 Client
PQ23435 Client hang with C++ forcereset between 2 asynchronous calls
PQ21700 Trap when multithreaded EPI program stresses client
PQ21621 C++ & OLE programs don't notice server has been restarted

APAR Fixes in v3.1.0
--------------------
PQ25891 Need choice to disconnect after TCP62 Dial Up
PQ27201 The Comma (,) is not allowed as a decimal point
PQ20693 ANYSOSDD is not needed with CICS Client TCP62 install on WinNT
PQ27690 VB application gets flow is active after an abend
PQ28928 Using interspace with Universal Client causes application termination
PQ28458 CICS Client - cannot use SBAS, RAS and EUA orders on screens
PQ30588 Large screen support for CICSPRNT
PQ27610 Truncated French message in password dialog box
PQ29611 Messages displayed in the CICSTERM window have wrong NL-characters
PQ30366 CICSTERM.EXE creates temp file in root directory
PQ27872 CCLLOG.TXT for CCL4413 needs to be changed from 'PORT=%U3' to 'PORT=%HD3'

APAR Fixes in v3.1.1
--------------------
PQ29864 Datastream3270.class incorrectly inserts zero byte at start of BMS fields
PQ31293 CCL8036 when using cicscli.ini on network drive due to 60 sec timeout
PQ32974 Config tool does not pick up mode names starting with hash
PQ33162 Default trace file name incorrect after file migrated
PQ33343 Cicsprnt does not work with /j or /p option ...
PQ33833 Cicsbmsc conversion utility put negative in 1st field of constant
PQ34080 If null passed to SETTEXT method in COM class field...
PQ34522 Shutting down client, when both client and CTG running, cause client  to hang
PQ34693 CICSTERM does not display  German umlauts correctly
PQ35123 During ATI processing, message 'CCL3227 Conversation (1) is not in send state' is intermittently received.
PQ35141 Trap in CCLCLNT process in the CICS client 3.1.0 for Windows NT defect 10080
PQ35237 Client blew up immediately at address 0x00AF209A which was trying to reference memory location x00000000
PQ35899 Tracing not working when running as service

APAR Fixes in v3.1.2
--------------------
PQ36608 Java applications using the local protocol under the Solaris JVM
        may crash if JIT enabled		
PQ36744 CICS Client may trap on shutdown
PQ37526 Trap occurs if servername called against a null CclConn object
PQ38268 A signed on signon-capable terminal loses its security when an
        ATI task is started against it
PQ38423 Automatic startup of CICS Client service may fail with Service
        Specific error 2006
PQ38960 TCP62 alias defined for partner LUs having the same applid on
        different networks
PQ39229 Client closes connection if TXSeries transaction times out
PQ39299 A new Terminal object may fail to run more than one transaction
PQ39790 CICS ComTerm sample/C++ classes do not handle 3270 correctly
PQ39866 CICSSetDefaultSecurity always fails
PQ39894 Cicsterm's IPC queue is not cleaned up on termination
PQ40115 Error codes in VB COM ECI samples are incorrectly translated


************************************************************************

IBM, AIX, CICS and OS/2 are trademarks of the IBM Corporation in
the United States or other countries.

Sun, Java and JavaBeans are a trademark of Sun Microsystems, Inc. in
the United States or other countries.

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

Adobe and Acrobat are trademarks of Adobe Systems, Inc. in the United
States or other countries.

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

************************************************************************
* (C) Copyright IBM Corporation 1999.  All rights reserved.            *
************************************************************************
************************************************************************
* End of file                                                          *
************************************************************************