SG 244237
SG 244237
SG 244237
May 1997
IBML
SG24-4237-00
International Technical Support Organization
May 1997
Take Note!
Before using this information and the product it supports, be sure to read the general information in
Appendix B, “Special Notices” on page 173.
• Version 2.2 of IBM VisualAge Generator Developer for OS/2, Program 5622-580 for use with the OS/2
Operating System
• Version 2.2 of IBM VisualAge Generator Workgroup Services for OS/2, AIX, and Windows, Program
5622-585 for use with the OS/2, AIX, and Windows Operating Systems
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
The Team That Wrote This Redbook . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Comments Welcome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Project Scope and Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Positioning VisualAge Generator Client/Server in the Open Blueprint . . . . . . 3
1.2.1 Open Blueprint Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 Critical Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 Integration Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 VisualAge Generator Communication Services Capabilities . . . . . . . . . . . . 8
1.3.1 CICS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3.2 Distributed Computing Environment . . . . . . . . . . . . . . . . . . . . . . . 12
1.3.3 VisualAge Generator Middleware . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.3.4 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.4 Implementing Client/Server Systems with VisualAge Generator . . . . . . . . . 16
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Figures vii
viii VisualAge Generator Client/Server Communications
Tables
1. Summary of VisualAge Generator Client/Server Communication Support for
Open Blueprint Integration Objectives . . . . . . . . . . . . . . . . . . . . . . . 16
2. DCE-Based Client/Server Communication Protocol Options . . . . . . . . . . 27
3. Primary Software Installed on CICS OS/2 Server Workstation . . . . . . . . . 30
4. DCE-Based Client/Server Communication Protocol Options . . . . . . . . . . 54
5. Common Problems Encountered During DCE Setup and Configuration . . . . 98
6. Common Problems Encountered During DCE Runtime . . . . . . . . . . . . . 100
7. Common Problems Encountered During DUOW Testing . . . . . . . . . . . . 136
8. Sample application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
This redbook was written for application developers and service professionals
involved in the design and implementation of VisualAge Generator client/server
systems. Some knowledge of VisualAge Generator, CICS, and client/server design
issues is assumed.
Rich Gast is a World Wide VisualAge Generator technical sales specialist. He has
worked at IBM for 13 years and has 8 years of experience in the field of client/server
computing. His areas of expertise include product development in DB2, DFSMS, and
ADSM in the areas of performance, client/server, and system management. He has
written extensively on client/server, performance, and system management topics for
both DB2 and ADSM.
Shengli Liu is a Technical Sales Specialist in the Peoples Republic of China. He has 5
years of experience in application development and is an IBM-certified DB2
Administrator.
Joan Zhao is a technical marketing specialist in the Peoples Republic of China. She
has 2 years of experience in application development, and has worked at IBM for 3
years. Her areas of expertise include VisualAge Generator client/server
communications. She has written extensively on DBCS-enabled client/server
configurations.
Thanks are also due to many people for their invaluable contributions to this project.
From the VisualAge Generator development lab:
John Ormerod
Comments Welcome
Your comments are important to us!
• Fax the evaluation form found in “ITSO Redbook Evaluation” on page 185 to the
fax number shown on the form.
• Use the electronic evaluation form found on the Redbooks Home Pages at the
following URLs:
This book studies the issues associated with selecting and implementing one of the
client/server communication configurations available for a VisualAge Generator
client/server application system.
The residency project that produced this book focused on the implementation of
selected client/server communication configurations so that we could explore the
basic functions of VisualAge Generator client/server communication support and offer
sample working configurations to help you in your environment.
Before you read this chapter, you may wish to review ″Chapter 1. Introducing
Client/Server Application Development″ in the Developing VisualAge Generator
Client/Server Applications manual. The referenced discussion is short, but very
appropriate; we therefore request that you at least review that chapter before reading
our publication.
Even with the power of VisualAge Generator, the design and implementation of a
client/server system presents a challenge. There are significant design decisions and
implementation issues that must be resolved.
During implementation, there are additional issues that must be resolved. Our view of
implementation issues is linked to the use of VisualAge Generator during development
and the configuration options for client/server communication provided by and
supported with VisualAge Generator.
1 VisualAge Generator is also a very good tool for host (3270 screen) application development, but the focus of this
book is client/server system implementation.
− Performance
− Administration
− Cost.
The work done to gain the experiences that are presented in this book reflect the
functions available in VisualAge Generator Version 2.2.
Given our focus and belief in the value of these open client/server communication
options we discuss arguments for a transition from the VisualAge Generator
proprietary middleware to these other client/server communication options.
This book does not attempt to explain all of the functions, options, and configuration
issues related to implementing a VisualAge Generator client/server application. It is
not intended to be your only guide in the process of implementing a VisualAge
Generator client/server application system. You should also use the publication
Developing VisualAge Generator Client/Server Applications as a reference and source
for initial guidance.
Significant skill with the underlying technologies used to support VisualAge Generator
client/server communication may be required to configure a working application
system.
The IBM Open Blueprint provides an architecture for open and flexible client/server
solutions. The IBM Open Blueprint is discussed in detail in:
In the Open Blueprint, the processes and functions of an open client/server system
are positioned in an architecture of interrelated application system components (see
Figure 3 on page 4).
Chapter 1. Introduction 3
Figure 3. Components of the Open Blueprint
Application-enabling services:
Presentation services define the interaction between applications and the user.
2 The Open Blueprint descriptive information presented in this chapter is from Introduction to the Open Blueprint: A
Guide to Distributed Computing .
Distributed-systems services:
Network services:
Systems management:
Provides facilities for a system administrator or automated procedures to
manage the network operating system.
The components defined as part of the Open Blueprint can help you to understand the
role and responsibilities that each logical component of an open client/server system
should perform. One or more products, or your application system if you choose to
write your own component services type of function, should implement the services
that are specific to each component in the Open Blueprint. In a client/server system,
some of these services are critical, so we review them in detail.
Application/Workgroup services
Application services provide high-level application- or workgroup-oriented
functions. They include:
Transaction Monitor
Transaction monitor is an industry term for functions that traditionally have
been included in IBM′s transaction processing systems. The Transaction
Monitor provides an environment for the development and execution of
applications, embodied in the transaction programs. The monitor typically
provides an application programming interface and support for efficient
transaction execution.
Chapter 1. Introduction 5
beforehand, such as address spaces, data, and other facilities. The
preallocation allows transaction programs to be scheduled efficiently.
The CICS transaction monitor API has been implemented on all major IBM
platforms and on many non-IBM platforms. The IMS transaction monitor
API has been implemented on a variety of platforms supporting
applications associated with MVS systems. The Encina transaction monitor
API has been implemented across a range of UNIX platforms.
Distribution services
Distribution services make a single-system view of the network possible.
Security
The security service protects network resources from unauthorized use by
registering users (both system and human) and their authorization levels,
by authenticating users, and by auditing access.
Time
The time service regulates the date and time across a network. The
transaction manager coordinates resource recovery across the various
systems in the network.
The current use of the term transaction manager differs from earlier usage.
This new terminology has been adopted to accurately reflect technical
goals and the functional parts of the Open Blueprint and to correlate with
standard industry terminology.
The main message we take from the IBM Open Blueprint in the context of this book
about VisualAge Generator client/server communications implementation is that each
component performs a specialized task and is both providing services to, and using
services of, other components defined in the architecture.
Single Sign-on
Lets the user have a single identification within the network. Here, network could
refer to one business or physical network or to multiple networks. Single sign-on
lets users log on with a single password and have access to all the network
facilities for which they are authorized.
Network-wide security
Protects network resources and users. It encompasses three basic areas:
Chapter 1. Introduction 7
• Resource access control to manage what a particular user can do
Network-wide directory
Provides information about resources in a network.
The directory eliminates the need for product-unique ways to locate resources,
and shields users from keeping track of where resources are located.
VisualAge Generator′s primary support for client/server systems is based on the use
of a remote procedure call (RPC) communication service between the client and the
server. This allows programmers to simply use the CALL statement to call server
applications and not worry about how the CALL is implemented at run time. VisualAge
Generator and client/server communication implement the difficult parts of
cross-system client/server RPC support.
VisualAge Generator applications can also use the conversational and message
queuing flavors of a communication service, but this support requires more design
Several methods are available for the implementation of RPC support when using
VisualAge Generator:
1.3.1 CICS
VisualAge Generator has an affinity for CICS. Many VisualAge Generator client/server
and 3270 stand-alone application functions are optimized for the CICS environment.
VisualAge Generator applications can be implemented on almost all of the available
flavors of CICS (MVS, VSE, OS/2, and Windows NT).
Our review of VisualAge Generator client/server systems that use the CICS-based
implementation of RPC support assumes the use of CICS Client or CICS OS/2 Client
software for client/server communication support. The use of a mixed environment
where VisualAge Generator middleware is used to connect to CICS is discussed in
1.3.3, “VisualAge Generator Middleware” on page 13.
3 VisualAge Generator intends to provide support for DCE RPC calls to MVS servers in future updates to VisualAge
Generator client/server communication support.
4 The VisualAge Generator middleware support provided with V1.0 was based on technology licensed from another
company. This licensed middleware function, packaged as part of VisualAge Generator runtime support products,
continues to be available in V2.2 of VisualAge Generator. IBM developed VisualAge Generator middleware
options for implementing VisualAge Generator client/server communication RPC support, such as IMS APPC and
CA/400, which are also available with V2.2.
Chapter 1. Introduction 9
CICS support for the Open Blueprint services, integration objectives, and
implementation issues identified previously are reviewed below: 5
Naming and Excellent. CICS naming conventions and the ability to refer to names
Directory in one CICS region that are physically implemented in another
connected CICS region provides application design flexibility and
support for distributing the workload required to manage different
resources. (Think in terms of file-owning regions, application-owning
regions, and terminal-owning regions.)
5 We have combined the assessment of the Open Blueprint security service support with the single sign-on and
network-wide security integration objectives. This discussion point is termed system security .
6 CICS OS/2 provides full support for recoverable resources when the resource is owned by CICS (files as well as
recoverable transient data queues and temporary storage). When other resources are used, such as a relational
database, CICS OS/2 provides a level of resource commitment coordination but does not fully implement a
coordinated resource management environment. (For example, a CICS synch point is processed independently,
but in concert with, a DB2/2 commit work.) This means that CICS OS/2 does not implement complete resource
management support for relational databases (such as DB2/2) while CICS/6000 does provide complete resource
management support for IBM and non-IBM relational databases.
The currently available version of CICS NT is based on the CICS OS/2 product. The next version of CICS NT will
be based on the CICS/6000 product. The resource coordination support for CICS NT will equal that provided by
the CICS/6000 code used as a base.
VisualAge Generator significantly reduces concern over this issue when a server-based logical unit of work (LUW)
management design is used. VisualAge Generator will expand commit and rollback requests as follows:
7 Depends on the CICS release level. Recent versions of CICS for host platforms support other security managers
only; that is, CICS stopped providing its own security system.
Chapter 1. Introduction 11
Administration Strong. Defining a connection between a CICS Client-enabled
workstation and a target CICS OS/2 or CICS NT workstation requires
that one file be updated (see 3.2.3, “CICS Client” on page 44). CICS
Client provides support for the NetBIOS, TCP/IP, and IPX protocols
when connecting to workstation targets. MVS and VSE connections
require SNA LU6.2 definitions and sessions.
Naming and Excellent. The fundamental architecture of DCE enables naming and
directory directory services.
Network-wide Excellent.
directory
A DCE cell provides a single point of server (service) definition and
the mapping to the physical location where the server (service) exists.
Global Excellent.
Transparent
All requests for a server (service) that is accessed using DCE-based
Access
client/server communication support are resolved at a single point.
This protects users from having to know if or when changes take
place in how servers (services) have been distributed in the network.
Chapter 1. Introduction 13
Many configurations are supported by VisualAge Generator middleware functions.
(These are reviewed in detail in Implementing VisualAge Generator Client/Server
Communication , GG24-4235.) Some of the available options, such as LU2 support, are
extremely valuable when a client workstation does not have a LAN connection (token
ring or Ethernet) to the enterprise network.
Other options, such as using TCP/IP to connect clients with servers running on OS/2
and AIX are attractive because no additional software is required, keeping costs down,
but the configuration lacks support for the services and integration objectives
identified earlier. 8
Using VisualAge Generator middleware to connect with CICS targets, given that a
gateway configuration that requires two hops to satisfy the server request is
mandatory, is not viewed as a reasonable option when compared with the
performance and relative ease of configuration of a CICS-based client/server
communication solution.
Transaction None when used to connect with native OS/2 or AIX applications.
monitor
Excellent when used to connect with IMS/DC. 9
Average when used in a gateway (two-hop) configuration with CICS as
the target server platform.
Transaction None when used to connect with native OS/2 or AIX applications.
manager
Excellent when used to connect with IMS/DC.
Average when used in a gateway (two-hop) configuration with CICS as
the target server platform.
8 The VisualAge Generator development lab may provide middleware support for TCP/IP client/server
communication processing between selected client and server platforms in the future. Customer requests for this
connection option are being evaluated. The services provided may not equal those provided by the CICS- or
DCE-based client/server communication options.
9 VisualAge Generator VisualAge Generator middleware support for the IMS/DC target is not as closed as other
VisualAge Generator middleware options. See ′Appendix E. VisualAge PowerServer APIs′ in the Developing
VisualAge Generator Client/Server Applications product manual.
Chapter 1. Introduction 15
1.3.4 Summary
Table 1. Summary of VisualAge Generator Client/Server Communication Support for Open Blueprint
Integration Objectives
VisualAge Generator
Objective CICS DCE
Middleware
Excellent with MVS CICS or Strong with MVS CICS or
Transaction IMS/DC server targets. IMS/DC server targets.
Excellent
monitor None when used with None when used with
workstation server targets. workstation server targets.
Naming and
Excellent Excellent Basic
directory
Time Strong Excellent Strong
Excellent with MVS CICS or Strong with MVS CICS or
Transaction IMS/DC server targets. IMS/DC server targets
Excellent
manager None when used with None when used with
workstation server targets. workstation server targets.
Strong with MVS CICS or
System IMS/DC server targets.
Excellent to Strong Basic
security Excellent when used with
workstation server targets.
Network-wide
Strong Excellent Basic
directory
Global
transparent Strong Excellent Basic
access
Performance Excellent Excellent Strong to Limited
Administration Excellent Strong Strong to Limited
Not a factor (provided by
Cost A factor A factor
VisualAge Generator)
In the rest of this book, we review the available VisualAge Generator client/server
configuration options.
Chapter 1. Introduction 17
18 VisualAge Generator Client/Server Communications
Chapter 2. Testing Applications with VisualAge
Generator Developer ITF
One of the powerful aspects of VisualAge Generator is the fact that you can test the
source code of your application independent of the runtime environment by using the
ITF. Database identification and access is controlled by the ITF.
In an ITF environment, both GUI and server applications run in a fully interpreted
mode; that is, testing using ITF simulates the runtime environment. 10 Of course,
because the entire application (clients and servers) are interpreted during testing in
ITF, processing is slower than it would be during runtime.
The ITF can also be configured to call executable versions of called applications (or
non-VisualAge Generator programs) instead of continuing to interpret, in test mode,
the called application. 11
Using executable versions of called applications can affect database identification and
access as well as LUW management.
This chapter discusses how calling generated applications is implemented by the ITF
and the implications for database identification and access authorization.
10 The goal of the ITF is to provide an exact simulation of the actual runtime environment. This goal is met in most
situations. Differences can occur when there are inconsistencies in the client/server configuration, LUW
management control techniques, and environment variable settings. If you think ITF is not simulating the runtime
behavior of your application, use your product support process to tell the IBM VisualAge Generator development
lab, which wants to know about and, if possible, correct the inconsistency.
11 Search on the text string “Calling external programs” in the VisualAge Generator Developer help facility for more
guidance on using linkage tables with the ITF.
• An accessible linkage table file indicates how the call should be implemented.
The active linkage table at runtime is the first linkage table found of either:
1. The linkage table identified during generation, minus the path information (The
linkage table is searched for in the current directory and then in the DPATH.)
LINKTYPE=oslink
A local call to an executable running on the same platform as the
VisualAge Generator Developer (OS/2) is issued. The called application or
program is located using the LIBPATH settings for the operating system.
LINKTYPE=remote
A remote call that is resolved using VisualAge Generator client/server
communication support. Standard client/server communication processing
logic is used. This begins with a second review of the active linkage table.
Client/server communication call processing logic rereads the active
linkage table. At this stage the active linkage table is the first found of:
1. A linkage table with the same name as that referenced in the ITF
general preferences profile (The drive and directory information is not
used to locate the linkage table. Client/server communication
processing searches for the linkage table in the current directory and
then in the OS/2 DPATH configuration setting.)
Database identification controls the name of the database to be used when SQL
statements are issued in an application running in a workstation environment.
Database authorization determines whether the application and the user are allowed
to access the tables in the target database and what qualifier is to be used for
unqualified table names.
When the application is run from the MSL, any database access is based on the DB2/2
configuration on the developer′s workstation. Access might be restricted to local
DB2/2 databases, or, by using distributed database support, to a database on another
workstation or host platform.
To identify a database to be used during the test session when no explicit database
connects have been coded in the application, indicate the database name in the
VisualAge Generator Developer profile. Select Profile and then Database
preferences... to change the name of the database used.
To issue SQL statements the VisualAge Generator Developer must be bound to the
target database. The first time the database is accessed through ITF or other
VisualAge Generator Developer SQL activity (such as SQL Record definition),
VisualAge Generator binds the eze2db2.bnd package to the database.
In addition to allowing VisualAge Generator Developer and the ITF to interact with the
database, the bind also determines the format in which date and time values are
returned to VisualAge Generator. If the format is incorrect, you can manually bind the
package to the database using the correct date/time format parameter:
The XXX indicates the datetime format to be used. See the DB2 documentation
appropriate for your DB2 database system for more information about binding a
package to the database.
If you are going to access a remote DB2/MVS database, you can identify the ID to be
used to qualify table names in the VisualAge Generator Developer database
preferences profile.
The use of the CSOUEXIT environment variable (see 2.2.4, “Runtime Database
Authorization” on page 23) can override the UPM value if the ITF is used to call
generated applications. When a generated application is called, the runtime
configuration is used to control processing. If the CSOUEXIT environment variable is
set for runtime processing, this can impact subsequent VisualAge Generator
Developer and ITF database authorization. The user ID and password obtained from
the CSOUEXIT identified authentication routine will be used for all subsequent SQL
processing by VisualAge Generator Developer and the ITF. 12
CSOUEXIT authentication is used for both database access and remote call security
(such as a call using the CICS Client ECI) so you may have to coordinate user
ID/password values across multiple platforms when you mix ITF SQL access and calls
to local and remote generated applications.
When ITF calls a generated application, database access is based on the physical
location (workstation or host) of the called application (or program) and the database
configured for the target runtime platform.
The database that is used during runtime execution of the application on a workstation
is determined by one of the following environment variables (when no explicit
database connects have been coded in the application):
• FCWDBNAME_appl
• ELARTRDB_tttt
• EZERSQLDB
• DB2DBDFT
See 5.2.1.4, “Identifying the DB2 Database” on page 108 for a detailed discussion on
the use of these environment variables. The setting of the appropriate environment
variable can be changed before you start the application or call the application from
the ITF. You may need to start the VisualAge Generator Developer environment from
an OS/2 command line if you want to customize any database or client/server
communication environment variable settings.
12 Note that this processing may change if Fixpaks are applied to VisualAge Generator.
Other environment variables can affect database selection for VisualAge Generator
applications. Please review Running VisualAge Generator Applications on OS/2, AIX,
and Windows for additional guidance.
Local calls can use UPM or CSOUEXIT processing to obtain the authorization ID used
for database access.
Remote calls to CICS targets will use CSOUEXIT processing to obtain the user ID and
password used for the CICS ECI interface. The user ID identified in the ECI call is not
always used for database authorization. Processing depends on the target CICS
platform and configuration.
In many situations CICS is the best choice for implementing client/server application
systems. CICS provides an unprecedented spectrum of possibilities:
• Synchronous and asynchronous communication services
• Support for a broad range of protocols
• Distributed data
• Distributed unit of work
• Multiple LUW management options
• Support for external security managers
• Security management in an N-tier environment
• Transaction management and monitoring
• Good performance in a multiuser transaction environment
• Stability of the operating environment
• Homogeneous environment on all CICS platforms.
3.1.1 Options
VisualAge Generator supports multiple configuration options in a CICS-based
client/server communication environment (see Figure 5 on page 26).
CICS Clients can provide direct access to CICS servers for two-tier configurations,
such as when a GUI client is directly connected to a CICS server. This two-tier
approach often provides the best available performance. For a detailed description of
CICS Client configurations, see CICS Clients Unmasked .
CICS is also ideal for N-tier architectures. This type of configuration allows remote
procedure calls (RPCs) to be satisfied at the first CICS platform or to be passed on to
another connected CICS platform. Applications can execute on the first server (acting
as an application server) or pass through the server (acting as a gateway) to another
CICS server by using Distributed Program Link (DPL) support.
Figure 5 shows both two-tier and N-tier configuration options for client calls to server
resources.
Protocol options between CICS Client and server platforms provide two-tier support.
Connections between CICS server platforms provide N-tier support.
The VisualAge Generator client uses the environment variable CSOLINKTBL to identify
the linkage table that will be used to determine how the remote call will be
implemented.
The LOCATION parameter is used to identify the CICS server that will receive the
application request. (This CICS server platform could pass the request on to another
CICS server using DPL support.)
CICS Client processing uses the CICSCLI.INI file to find information about how the
remote procedure call to the requested CICS server will be implemented. Protocol
and destination options are identified in the CICSCLI.INI file.
Finally, control is passed from the CICS Client to the CICS server via the ECI interface.
On the server side, CICS authorization is performed as required in the CICS server
connection configuration. This can be based on the transaction ID associated with the
server request. The transaction-invoked CPMI (or user-defined if a SERVERID value is
specified in the linkage table) executes the DFHMIRS CICS-supplied catcher program
which, in turn, starts the called application specified in the APPLNAME parameter of
the active linkage table entry used for this call.
The LUW can be committed either at the server or by the client, which depends on the
application design and the linkage table entry being used.
• CICS OS/2
• CICS NT
• CICS/6000
• MVS CICS
• VSE CICS
VisualAge Generator client applications can access CICS servers using CICS Client
support from these client platforms:
• OS/2
• Windows NT
• Windows 95
• Windows 3.11
• VisualAge Generator client applications that use CICS Client support for
client/server communication.
Configuring CICS servers can be a complex task, depending on the target operating
system. However, configuring CICS-based client/server communication support for
VisualAge Generator clients is very easy using the CICS Client software.
We wanted to support CICS Client connections to this server platform using both
NetBIOS and TCP/IP options. The output of generation activity was shared with other
workstations in our configuration using LAN Server. Generation processing is
discussed in Appendix A, “Sample Applications” on page 163.
1. We had to apply service, termed CSD1, to IBM VisualAge COBOL before it would work
for VisualAge Generator application preparation.
The installation of each of the products shown in Table 3 automatically updates the
OS/2 CONFIG.SYS as required for basic product operation. Any additional updates to
CONFIG.SYS that we made are identified in 3.2.1.2, “Configuration and Customization.”
These tasks are reviewed in detail below. You should review the appropriate chapters
in Installing VisualAge Generator Workgroup Services before beginning this activity.
UPM OS/2 User Profile Manager. UPM delivered with CM/2, DB2/2, and
upgraded if LAN Requestor or LAN Server is installed.
NONE Private security. Do not choose this option unless you have a working
security exit configured for CICS OS/2 . The choice of NONE does not
mean no security, it means that CICS OS/2 will ask your configured
CICS security exit (FAAEXP07) to make access decisions. If you do not
have a security exit configured after you have selected the NONE
option and shut down CICS OS/2, you cannot start CICS OS/2 again
until:
The SIT entry selecting UPM as the security manager is shown in Figure 10 on
page 33.
System Sizes
CWA size. . . . . . . . . . . . . : 0
Maximum TWA size. . . . . . . . . : 1024
Trace table size. . . . . . . . . : 500
Task Control
System Communications
Local System ID . . . . . . . . . : CWGS
Local System Appl ID. . . . . . . : CICSWGS2
Default Remote System ID. . . . . :
NetBIOS Support
NetBIOS Listener Adapter. . . . . : 0 (0, 1 or B)
Maximum NetBIOS Systems . . . . . : 3 (0-254)
TCP/IP Support
TCP/IP Local Host Name. . . . . . : *
TCP/IP Local Host Port. . . . . . : 1435 (* or 1-65535)
Maximum TCP/IP Systems. . . . . . : 10 (0-999)
PNA Support
Load PNA Support. . . . . . . . . : N (Y or N)
PNA Model Terminal. . . . . . . . :
Figure 9. CICS OS/2 SIT—Page 2
Security
Miscellaneous
Figure 10. CICS OS/2 SIT—Page 3
/*---------------------------------------------------------------------*/
/* Determine if this program has already been run in this environment. */
/*---------------------------------------------------------------------*/
if GetValue(execname||′ _ RUN′ ) = ′ ′ then
do
..
.
′&WGS ELAENV Logic′
..
.
end /* end-if this program has not been run */
exit
If you are not aware of the bypass logic in the ELAENV.CMD and change the
command settings to correct problems discovered during preparation, you may
not realize why your changes do not seem to take effect. You need to open a new
OS/2 window or reset the ELAENV_RUN environment variable to nulls so that the
logic of ELAENV.CMD does not immediately force an exit.
We made the following changes to the settings in the ELAENV.CMD that control
where products are installed and which COBOL product (IBM or Micro Focus) we
are using in our environment (see Figure 12 on page 34).
ela_install_dir = ′ \VGWGS2′
cics_install_dir = ′ \CICS300′
cobol_install_dir = ′ \IBMCOBOL′
default_ezernls = ′ ENU′
default_database = ′ SAMPLE′
ela_bit_mode = ′32′
ela_cics_group = ′ VGWGS′
cics_version = ′3.0′
call_cicsenv = 1
user_work = ′ E:\VGCS\GENOUT\OS2CICS′
cobol_type = ′ IBM′
4. Start CICS OS/2 using the Start CICS OS/2 with IBM VisualAge Generator Support
icon in the Workgroup Services folder.
The steps that remain are done inside CICS OS/2.
c. Run the CAIM transaction to import the contents of the FAAAEIE.BTR file.
This file contains the VisualAge Generator Workgroup Services definitions
used in CICS OS/2.
The CAIM transaction menu options suggested in the section ″Importing the
VisualAge Generator Workgroup Services CICS Resources″ of the Installing
VisualAge Generator Workgroup Services did not work for us when using CICS
OS/2 V3.
The following discussion, extracted from an online discussion about CICS OS/2,
tells us why and what to do instead.
---------------------------------------------------
Subject: Problems with CAIM import in CICS OS/2 3.0
What do we do now?
-------------------------------------------------
Subject: Problems with CAIM import in CICS 3.0
The file became enabled but when I try to execute the CAIM transaction
I get the same error. When I checked again with with ″CEMT I FILE″
transaction I see that the FAAAEFIE.BTR file was closed and disabled
again.
When I restarted CICS the file was open and enabled but when I issued
the CAIM transaction I got the same error.
Do I miss something?
-------------------------------------------------
Subject: Problems with CAIM import in CICS 3.0
I believe you can still import and export groups resetting the file
open and enabled each time.
-------------------------------------------------
Subject: Problems with CAIM import in CICS 3.0
After the import has run it will be necessary to use CEMT to enable
the file.
So we used the CEMT transaction to ensure that the FAAAEIE.BTR file was
enabled and then used the CAIM transaction to import the VGWGS group. This
file contains the VisualAge Generator Workgroup Services definitions.
We did not import the EZERSMP group. There is an empty/missing file referenced
in the EZERSMP group that causes messages to be displayed when starting CICS
OS/2. We did not want to use the VisualAge Generator sample applications, so by
not importing the EZERSMP group we avoid triggering these warning messages.
6. Update customized SIT to set the Transaction Work Area (TWA) to 1024
VisualAge Generator transactions in a CICS environment use TWA resources.
CICS must be told to reserve the number of bytes used by VisualAge Generator
CICS applications. The SIT entry for TWA is visible in Figure 8 on page 32.
7. Shut down CICS OS/2 with the CQIT transaction or by closing the CICS OS/2
monitor window.
8. Start CICS OS/2 using the Start CICS OS/2 with IBM VisualAge Generator Support
icon in the Workgroup Services folder.
We could either set the value for EZERSQLDB in CONFIG.SYS or use the
ELAENV.CMD file option for setting the default database name for VisualAge
Generator Workgroup Services applications. We defined a default database name
of SAMPLE in the ELAENV.CMD file (see Figure 12 on page 34).
Sample application generation and preparation: Two sample application servers were
generated for the CICS OS/2 target runtime platform. They support remote calls from
VisualAge Generator clients using either CICS-based or VisualAge Generator
Middleware-based client/server communication support.
We have two servers that are part of the sample application that must be generated
for CICS OS/2: VGC2OS2 and VGC3OS2. Server VGC2OS2 will be called by the
sample application GUI client. Server VGC3OS2 will be called by a sample application
server when a three-tier server call to CICS OS/2 is requested. The generation
process is as follows:
Figure 13. Linkage Table for CICS OS/2 Sample Application Servers
During generation, the critical options are PARMFORM and LINKTYPE. We can change
the REMOTECOMTYPE value used during the actual call from a client or non-CICS
server and still reach these CICS server applications.
/COBOL=IBM
We need this option since we are using IBM COBOL. The default, for
compatibility with previous releases of VisualAge Generator, is to generate Micro
Focus COBOL if no COBOL option is specified.
Figure 14. Generate Statements for CICS OS/2 Sample Application Servers
We included the /trace generation option so that we could trace the execution of
the server applications in CICS OS/2. This option is not recommended for
production servers, because of the heavy overhead associated with an application
that includes trace support. You must turn trace support on before the
applications are traced in a CICS environment. The VisualAge Generator
Workgroup Services ELAZ transaction is used to start trace support for VisualAge
Generator applications. See Installing VisualAge Generator Workgroup Services
for guidance on using the ELAZ transaction.
Our generation output directory is the same as the user_work directory identified
in the ELAENV.CMD file (see Figure 12 on page 34).
Because of this, we must lower CICS OS/2 before preparation. If we do not stop
CICS OS/2 and we have called previous versions of the servers, preparation will
fail because the dynamic link library (DLL) has been loaded and is locked by the
CICS OS/2 process. The following message results:
CICS OS/2 Transaction Definition: To directly run a program in CICS, you must have
a transaction definition. The transaction definition identifies the program that should
be started when the transaction ID is entered.
When a program is run in CICS OS/2 using the External Callable Interface (ECI)
programming interface you can identify a transaction ID to be used to support the
requested program. VisualAge Generator supports the definition of a transaction
value in the ECI call by using the SERVERID linkage table option.
By default, CICS OS/2 uses the transaction CPMI when no transaction ID is identified
as part of the ECI call. The CPMI transaction will start a program named DFHMIR.
This mirror program issues a CICSLINK to the program requested using the ECI
interface. The process is as follows:
• Define a private transaction for sample application servers called using the CICS
OS/2 ECI.
We wanted to support CICS Client connections to this server platform using the TCP/IP
protocol option. The generation activity performed on the CICS OS/2 server, which
also supports VisualAge Generator application generation, directs files to this AIX
workstation for preparation processing.
3.2.2.1 Software
The primary software installed on our CICS/6000 server platform is listed in Figure 15.
AIX V4.1.3
CICS for AIX V2.1.0
ENCINA server V2.1.0
Workgroup Services for AIX V2.2.0
C Set++ for AIX V3.1.3
DB2/6000 V2.1.0
DB2/6000 options installed:
- DDCS
- DB2 Server, Single User
and Client Enabler
- Communications support:
DRDA AS, IPX, TCP/IP, SNA
3.2.2.2 Install Process for VisualAge Generator Workgroup Services for AIX
If an earlier version of VisualAge Generator Workgroup Services is already installed, it
must be removed before installing a new version.
installp -u vgwgs20.obj
To install the new VisualAge Generator Workgroup Services image, use the following
command:
To enable TCP/IP connection support you must define a listener for your CICS/6000
region and add a new service name to the TCP/IP configuration. The configuration
that we describe is based on our CICS/6000 region named vgsmc . The process is as
follows:
smit
- Applications
- Customer Information Control System (CICS) Version 2
- Manage CICS Regions
- Define Resources for a CICS Region
- Manage Resources
- Listeners
- Add Listener
The TCP Adapter Address and the Service name are left blank. This means we
are using the defaults; CICS can use any of the TCP/IP adapters on the machine
and uses the 1435 service port. You can also specify a service:
1. Set the environment variables in the environment file for the CICS/6000 region.
The environment file can be found in the directory /var/cics_regions/regionName.
For the SAMPLE database on AIX, we use the following settings:
DB2INSTANCE=db2
EZERNLS=ENU
FCWDB2DIR=/usr/lpp/db2_02_01
FCWDBUSER=db2
FCWDBPASSWORD=DB2
EZERSQLDB=SAMPLE
FCWLIBPATH=/u/vgcsres/genout
FCWDPATH=/u/vgcsres/genout
LIBPATH=/usr/lpp/vgwgs22/lib
FCWTROPT=31
FCWTROUT=/var/cics_regions/vgsmc/data/FCWTRACE.OUT
export CICSREGION=vgsmc
fcwcicsinstall
cicsinstall -r vgsmc -g VGWGS
Create a DB2 Shared Object: CICS transactions and Workgroup Services both refer to
the DB2 shared object at run time. This DB2 object library is needed in the
preparation of the VisualAge Generator applications.
• To create the DB2 shared object, issue the following commands:
cd /user/lpp/db2_02_01/lib
ar -vx libdb2.a
mv shr.o db2.o
ln -s /usr/lpp/db2_02_01/lib/db2.o /usr/lib/db2.o
Create an AIX User and Customize the User Profile: To support VisualAge Generator
application preparation for the CICS/6000 target runtime environment you need to be
able to transfer the generated C + + source and the preparation command file to the
required RS/6000 workstation. To do this, create a user that has all the required
environment variables defined in the user profile:
As an alternative, you can also execute the profile of the DB2/6000 instance that
you want to use. Add the following line to the user ′s profile:
. /home/db2/sqllib/db2profile
You need to specify a hostname, a user ID and password. In our example, these are
′vgrisc,′ ′vgcsres,′ and ′secret,′ respectively. If you have the authority, the ls (the AIX
dir command) will be executed.
The hostname, user ID, and password are used later as values for these generation
options: /DESTHOST, /DESTUID, and /DESTPASSWORD.
Generation Options for AIX CICS: The following preferences in the options file are
used for the generation of our sample application:
Linkage Table for AIX CICS: The linkage table for generating remote applications for
CICS/6000 used in the sample application is shown in Figure 16.
Figure 17. Generate Statements for CICS OS/2 Sample Application Servers
Defining Programs to CICS/6000: The generation process also creates a script that
defines the generated application in CICS. It adds a program definition and a
transaction definition to the CICS tables. When you do not want to define transactions
for your server programs, all programs can run under the CPMI mirror transaction.
However, for main applications (text clients) that run in CICS/6000, you are required to
specify a transaction. Otherwise you have no way to start the application!
The CICS script for an application is named ′ < applicationName>c.scr′. A script for
adding application VGC2AIX to CICS is shown in Figure 18 on page 44.
The generated script does not contain the flag ′R S L K e y = p u b l i c ′. We added this flag
to set the authority to call the program and transaction remotely. We also changed
the transaction ID to VGCS.
chmod +x vgc2aixc.scr
vgc2aixc.scr
Now the applications are defined in CICS. To make them active, shut down and
restart CICS.
Shutting Down and Restarting CICS/6000: There are special considerations when you
use a DCE, Encina SFS, and CICS/6000 configuration. Shutting down and restarting
CICS is clearly described in the CICS/6000 publications.
• A valid working CICS Client configuration (defined in the CICSCLI.INI file) that
points to the required CICS server.
3.2.3.1 Option File and Linkage Table for GUI Application Generation
We used the default option file (EFKOPDFT.OPT) for GUI application generation. The
GUIs in our sample application were generated for both the OS/2 and Windows client
platforms (see Figure 19).
Figure 19. Sample Application Generation Commands for GUI Client. Embedded GUI
applications are generated as a result of the /GENEMBEDDEDGUIS default generation option.
Sample application servers are generated with support for remote calls. Generation
of the servers is discussed in the platform-specific CICS server topics:
The linkage table option of REMOTEBIND=runtime is always used by a GUI application, but
only for calls generated as remote. Figure 20 shows the linkage table entries used for
generation for the remote CICS workstation-based servers that are called by the GUI
client in our sample application.
Figure 20. Linkage Table used to Generate Sample Application GUI Client for CICS
Servers
The LOCATION and SERVERID :CALLLINK options are not required at generation time.
CICS Client configurations, as defined in the CICSCLI.INI file, are very similar for OS/2,
Windows 95, and Windows NT. Figure 21 on page 47 contains the server definition
section of a CICSCLI.INI file.
;-----------------------------------------------------------------------
; Server section - This section defines a server to which the client may
; connect. There may be several Server sections.
;
Figure 21. CICSCLI.INI Defintions for Workstation CICS Servers. Only a portion of the
full CICSCLI.INI file is shown. The definitions for the communication drivers used for each
supported protocol are given at the bottom of the full CICSCLI.INI file. See the CICSCLI.INI file
included as part of a CICS Client installation on your selected target operating system for
additional descriptive information and CICS Client communication driver configuration.
Multiple protocol options are supported when connecting CICS Client with CICS server
systems. The protocol you select may be based on existing company standards, local
preferences, or compatibility with other products used on the end-user′s client
workstation.
CICS Client protocol support is reviewed in 3.1.2, “Protocol Choices” on page 26. For
additional guidance on CICS Client configuration options, please consult CICS Client
documentation and CICS Clients Unmasked , SG24-2534-01.
The following settings and commands configure VisualAge Generator GUI runtime
support options and start the GUI client application:
SET CSOLINKTBL=d:\filename
Name of linkage table to be read to support runtime binding of remote calls
SET CSOUEXIT=userauth
Name of user authentication routine that provides user ID and password values
used in client/server communication
SET CSOTROPT=n
Sets client/server communication trace options. A value of two traces all
client/server calls.
SET CSOTROUT=d:\filename
Defines location of client/server communication trace output file.
Figure 22 shows the linkage table entries used at run time (referenced by
CSOLINKTBL) for the remote CICS workstation-based servers that are called by the
GUI clients in our sample application.
Figure 22. Linkage Table used for Runtime GUI Client Calls to CICS Servers. The
REMOTECOMTYPE=cicsclient option identifies the use of CICS-based client/server communication
support. The LOCATION option is used to identify the target CICS system name as defined in the
CICS Client configuration file. The SERVERID option identifies the CICS transaction ID that should
be used as part of the ECI call. If SERVERID is not used, the default transaction ID of CPMI is used
to support the request.
When we run the sample application and call a server using CICS-based client/server
communication support, if we use the CSOTROPT=2 environment variable setting, we
then can see in the CSOTRACE.OUT file how the processing is implemented (see
Figure 23).
<Jan 15 09:43:53>->CMINIT
<Jan 15 09:43:53><-CMINIT - 0.029291 s
<Jan 15 09:43:53>->CMCALL
<Jan 15 09:43:53> Calling application VGC2OS2
<Jan 15 09:43:53> ->readFromLinkTbl
<Jan 15 09:43:53> <-readFromLinkTbl - 0.207975 s
<Jan 15 09:43:53> ->loadAndInitDriver
<Jan 15 09:43:53> <-loadAndInitDriver - 0.323233 s
<Jan 15 09:43:53> ->CMDV_INIT
<Jan 15 09:43:53> ->CICSCLIENT:CMDV_INIT
<Jan 15 09:43:53> <-CICSCLIENT:CMDV_INIT - 0.028159 s
<Jan 15 09:43:53> <-CMDV_INIT - 0.084962 s
<Jan 15 09:43:53> ->CICSCLIENT:CMDV_CALL
<Jan 15 09:43:59> CMDV_CALL: LuwType=SERVER
<Jan 15 09:43:59> ->CICSCLIENT ECI_CALL
<Jan 15 09:44:06> <-CICSCLIENT ECI_CALL - 7.567954 s
<Jan 15 09:44:06> <-CICSCLIENT:CMDV_CALL - 14.583481 s
<Jan 15 09:44:06><-CMCALL - 15.405744 s
Figure 23. CSOTRACE.OUT Entries for GUI Client Call to CICS OS/2 Server
When the ITF calls a generated application, the generated application acts very much
like a GUI client application. A valid client/server communication configuration is
required.
Calling generated applications from ITF can impact database identification and
authorization processing (see Chapter 2, “Testing Applications with VisualAge
Generator Developer ITF” on page 19).
The program on the remote CICS OS/2 system must also be defined to CICS/6000 as a
remote program (see Figure 25).
Figure 25. CICS/6000 Program Definition for Remote CICS OS/2 Program
With the connection implemented and the remote program defined, you can use the
VGPING sample application to implement a call from the GUI client to the tier-2 server
VGC2AIX and then to the tier-3 server VGC3OS2. Figure 26 on page 51 shows the
VGPING sample application GUI with the results after such a call.
Session Details
Session Count. . . . . . . . . . : 10 (1-99)
Session Buffer Size. . . . . . . : 40000 (512-40000)
Attach Security. . . . . . . . . : V (L=Local, V=Verify)
Partner Code Page. . . . . . . . : 00037
TCP/IP Details
Local host name. . . . . . . . . : *
Remote host name . . . . . . . . : VGRISC.RALEIGH.IBM.COM
Remote host port . . . . . . . . : * (1-65535, or *)
The program on the remote CICS/6000 system must also be defined to CICS OS/2 as a
remote program (see Figure 28 on page 52).
Resident(P,T,N). . . . . . . . . . . : N (P, T or N)
Figure 28. CICS OS/2 Program Definition for Remote CICS/6000 Program
With the connection implemented you can use the VGPING sample application to
implement a call from the GUI client to the tier-2 server VGC2OS2 and then to the
tier-3 server VGC3AIX. Figure 29 shows the VGPING sample application GUI with the
results after such a call.
Figure 29. VGPING Sample Application GUI after Three-Tier Call: GUI to CICS OS/2 to
CICS/6000
4.1.1 Options
VisualAge Generator supports multiple configuration options in a DCE-based
client/server communication environment. DCE-based client/server communication
supports the use of VisualAge Generator clients with servers generated for native
execution on the AIX, OS/2, and Windows NT workstation operating systems. DCE
also provides support for calls to servers running on the MVS CICS and IMS/VS host
transaction platforms and the VM/ESA host environment (see Figure 30 on page 54).
(1) NetBIOS is supported by IBM Directory and Security Server for OS/2 Warp Version 4.0
configuration-file name
The configuration file specifies which VisualAge Generator server
applications are available (can be called) on the application server.
13 There is a problem with VisualAge Generator V2.2 at the Fixpak 3 level. The documented default parameter (-c)
must be used to trigger the related processing. If -c is not provided, the CSODCES program runs as if the -d
parameter was provided, which makes the -d parameter the effective default. The -d parameter, when used,
causes an error message (Could not open data file, -d).
5. The DCE Client is started on the client workstation. Information about servers
defined in the DCE cell is shared with the client (CDS data).
If secure client/server communications are configured (REMOTECOMTYPE=dcesecure)
and the appropriate DCE authorizations are defined, the end user must perform a
DCE logon.
Once DCE Client software has been started and a DCE logon established,
VisualAge Generator client applications can call VisualAge Generator servers
applications using DCE RPC support.
• OS/2
• Windows NT
• AIX 4.1.3
The use of DCE-based client/server communication requires that a DCE cell server
exist. We used the AIX 4.1.3 workstation as our cell server.
OS/2 or Windows NT could also have been configured as a DCE cell server with the
appropriate software installed (see your DCE product documentation). For additional
information about implementing a DCE cell review, see
DCE Client
The software required to support DCE-based client/server communication. DCE
Client is required on both the GUI client and application server workstations.
CDS Client
The software required on the application server workstation to support the
DCE-based client/server communication.
DCE Cell
The named environment or domain that supports communication between
member workstations. VisualAge Generator uses the RPC subset of a DCE
environment to implement client/server communication support.
All the workstations shown in Figure 32 must have TCP/IP installed and configured to
support DCE client/server communication. To test whether TCP/IP is installed and
configured correctly, PING the host name of any of the other workstations from any
workstation. Each workstation should be able to PING all other workstations that will
be used in the DCE configuration.
Figure 33 shows the PING command used to test TCP/IP communication to the AIX DCE
cell server.
[H:\vgcs]ping vgrisc.raleigh.ibm.com
PING vgrisc.raleigh.ibm.com: 56 data bytes
64 bytes from 9.67.172.228: icmp_seq=0. time=187. ms
64 bytes from 9.67.172.228: icmp_seq=1. time=125. ms
64 bytes from 9.67.172.228: icmp_seq=2. time=125. ms
Figure 33. PING Command Used to Test TCP/IP Communication between Workstations
• A client (end user) DCE logon is not required unless a secure DCE-based call
(REMOTECOMTYPE=dcesecure) is required.
DCE supports the management of sets of user principals with the organization and
group constructs.
We define a DCE principal for each end-user and each application-server workstation.
DCE organization and group capabilities are used to define roles and authorities for
each set of (client and server) principals.
The following groups and principals are defined as part of an organization named
visgen :
In several of our scenarios, we do not call VisualAge Generator servers that run on
AIX. We use the AIX workstation only as the DCE cell server that enables our choice
of DCE-based client/server communication for our VisualAge Generator sample
application system. We could have implemented DCE cell server support on the OS/2
or Windows NT workstation platforms, or even on a host system if we did not want to
use the AIX workstation as the cell server.
We had the following software on our AIX DCE cell server workstation:
We have ignored the other software installed on the AIX workstation as they were not
directly involved in this DCE-based client/server communication configuration.
smitty dce
When no DCE cell is defined or you do not want to use an existing DCE cell, you can
create a new one. Refer to the appropriate DCE manual for your environment for
information about creating a DCE cell.
In the following configuration steps, we assume that you already have defined a DCE
cell, a clearinghouse, and a cell administrator cell_admin .
Figure 34. Defining DCE Organizations, Groups, and Users on AIX Cell Server with
dcecp. The cell_admin password is used as part of the dcecp command when creating users.
Passwords for the individual users are also defined. The -inprojlist yes parameter ensures that
users in a group accrue the access rights permitted to the group.
Figure 35. Defining Base DCE Directories on AIX Cell Server with dcecp
Target directories specific to the particular application system are created for the
configured SERVERID value in this directory structure after authorities for the base
directory are defined.
3. Configure the required application server principal authority for the CDS base
directory structure.
A DCE principal is identified in the configuration file passed to the DCE server
program CSODCES. The DCE principal is used to enter the DCE cell and create
or update the objects in the target directory (/.:/Servers/VAGenerator/SERVERID).14
To perform these operations certain privileges must be defined for the principal.
In DCE, authorization for specific tasks is controlled by access control lists (ACLs).
Each ACL entry for a user, group, or other DCE resource has a set of allowed
authorities. These are the authorities for CDS ACL entries:
14 During our testing, we determined that the target directory name, as determined by the SERVERID value, was
restricted to eight characters. This limit may be removed at a later date. If you require names longer than eight
characters make a request to the IBM VisualAge Generator development lab for service.
OBJECT ACL
Controls access to any CDS name (object entries, soft links, child
pointers, clearinghouses, and directories).
If we look at the OBJECT ACL for the base directory (see Figure 36) we can see
that the group subsys/dce/cds-admin has the required authority.
acl_edit /.:/Servers/VAGenerator -l
Figure 36. OBJECT ACL for VisualAge Generator DCE Base Directory
The easiest (but not the recommended) way to obtain the CDS privileges required
is to add the application server principal to the CDS administrator group
(subsys/dce/cds-admin). If you are logged in as cell_admin , you can issue the
dcecp command shown in Figure 37 to add user vgos2sj1 to the CDS
administrator group (cds-admin).
The problem is that CDS administrator privleges far exceed the actual
requirements of an application server principal. The DCE server program
CSODCES must be able to create and update the objects in the target directory
(/.:/Servers/VAGenerator/SERVERID).
However, the group subsys/dce/cds-admin has the listed authority (rwdtcia) on
every directory in the DCE Cell (this is not shown in Figure 36).
We can provide the application server principal with the required authority on only
the base directory (and any future target directories) by adding an entry for the
acl_edit /.:/Servers/VAGenerator -l
Figure 38. Adding Authority for Base Directory to Application Server Group.
Commands to add OBJECT, INITIAL OBJECT, and INITIAL CONTAINER ACLs are shown along
with a command that lists the current OBJECT ACL entries for the directory. Similar results
would be seen for an INITIAL OBJECT or an INITIAL CONTAINER ACL list.
Figure 39. Removing Test Authority on Base Directory for unauthenticated and
any_other ACL Entries. Commands to modify the OBJECT, INITIAL OBJECT, and INITIAL
CONTAINER unauthenticated and any_other ACL entries are shown, along with a command that
lists the current INITIAL CONTAINER ACL entries for the directory. Similar results would be
seen for an OBJECT or an INITIAL OBJECT ACL list.
The changes shown in Figure 38 on page 63 and Figure 39 prepare the base
directory for unauthenticated and authenticated VisualAge Generator DCE-based
client/server communication without allowing the application server principals
unneeded authorization for the full CDS directory structure.
15 In the manual Developing VisualAge Generator Client/Server Applications DCE examples used a SERVERID value
of TEST. We confused this with the ACL test authority, which is why we did not use a SERVERID value of TEST.
Figure 40. Creating Target DCE Directory on AIX Cell Server with dcecp
Because we had already implemented our ACL entries for the base directory (see
Figure 38 on page 63 and Figure 39 on page 64) we automatically get the
authority required on the target directory (see Figure 41).
acl_edit /.:/Servers/VAGenerator/vgcs -l
Figure 41. OBJECT ACL List for VisualAge Generator DCE Target Directory
Our DCE cell is now ready to support VisualAge Generator DCE-based client/server
communication.
To implement the DCE application server workstation we had to install and configure
DCE and then set up the DCE server program CSODCES. We also generated the OS/2
server portion of the sample application.
To configure the DCE client, you must identify the name of your DCE cell and the host
names of your cell directory server and the security server. In our configuration, we
ran the CDS, security, and DTS servers on the AIX DCE server workstation. On the
DCE application server workstation, we configured CDS, security, and DTS clients. We
During our experimentation we disabled our DCE client on OS/2 several times. When
this occurred, we would reconfigure to correct the DCE problems. Reconfiguration
using the Configure DCE Services function required these steps:
2. On the Cell Administrator and Password page select Complete local host
configuration and run the configuration process.
Repeat the previous two steps if any errors occur during the process of removing
the configuration of directory, security, or DTS client support.
3. Reconfigure using the same process as the initial configuration activity once you
have successfully removed the configuration from all clients.
This would reset our DCE client configuration and allow us to use DCE services again.
Note: Removing and reestablishing the DCE configuration removed any entries we
had made in the keytab file on the DCE application server workstation. We had to use
rgy_edit to add the principal again (see Figure 54 on page 77).
• We have two servers that are part of the sample application that must be
generated for OS/2 with DCE-based client/server communication support:
VGD2OS2 and VGD3OS2. Server VGD2OS2 is called by the sample application
GUI client. Server VGD3OS2 is called by a sample application server when a
three-tier server call to an OS/2 platform using DCE-based client/server
communication is requested.
1. Define linkage table for DCE sample application servers. Figure 42 shows the
linkage table entries we used to generate the VGD2OS2, VGD3OS2, and VGL3OS2
applications.
Figure 42. Linkage Table for OS/2 Sample Application Servers with DCE-Based
Client/Server Communication Support. Linkage table entries are included for both the
servers being generated and the servers that can be called from VGD2OS2.
Figure 43. Generating OS/2 Sample Application Servers with DCE-Based Client/Server
Communication Support. Both the local and the remote DCE-based sample application
servers are generated for OS/2. This provides support for multiple two- and three-tier
computing configurations.
You are now ready to configure and start the DCE server program on this workstation.
This process is nearly identical on OS/2, Windows NT, and AIX server platforms. For
this reason, we describe it only once in 4.2.7, “Running Applications with DCE-Based
Client/Server Communication” on page 75.
We used the following software for the OS/2 DCE GUI Client:
To implement the DCE GUI client workstation, we had to install and configure DCE.
We also generated the OS/2 GUI client portion of the sample application.
To configure the DCE slim client you need the cell name and the TCP/IP names or
addresses of the CDS and security server. In our configuration, we ran the CDS,
security, and DTS servers on the AIX DCE server workstation. You do not have to
provide the cell administrator′s password, because configuration tasks are not
performed on the DCE cell server. We provided these values and made these
decisions when configuring the DCE slim client using DSS for OS/2 Warp:
During our experimentation, we disabled our DCE client on OS/2 several times. When
this occurred, we would reconfigure to correct the DCE problems. Reconfiguration
using the Configure DCE Services function required these steps:
2. On the Cell Administrator and Password page select Complete local host
configuration and run the configuration process.
3. Reconfigure using the same process as the initial configuration activity once you
have successfully removed the configuration of all clients.
This would reset our DCE client configuration and allow us to use DCE services again.
The sample application GUI client can directly call a second-tier DCE-based server
application on the OS/2, Windows NT, or AIX platforms. Third-tier DCE-based servers
could also be called from the OS/2 client platform if we generated the local C+ +
server included in the sample application (VGL2OS2).
The following steps are required to build the VisualAge Generator client platform
applications:
1. Define linkage table for all possible OS/2 client platform calls to DCE sample
application servers.
Figure 44 shows the linkage table entries we used to generate the sample
application GUI client and local C + + server to support second- or third-tier calls
to OS/2, Windows NT, or AIX platforms.
Figure 44. Linkage Table for OS/2 Sample Application Client with DCE-Based
Client/Server Communication Support
Figure 45. Sample Application Generation Commands for OS/2 Client for DCE-Based
Client/Server Communication. Embedded GUI applications are generated because of the
/GENEMBEDDEDGUIS default generation option.
To implement the DCE application server workstation, we had to install and configure
DCE and then set up the DCE server program CSODCES. We also generated the
Windows NT server portion of the sample application. To install DCE support on
Windows NT we did the following:
The DCE server program CSODCES provided by VisualAge Generator requires a full
DCE client installation. This means that we must install or configure support for the
CDS Client as part of the DCE installation.
To configure full DCE client support with Gradient′s PC-DCE/32, you need the cell
name and the TCP/IP names or addresses of the CDS and Security server. In our
configuration, we ran the CDS, security, and DTS servers on the AIX DCE server
workstation. We provided these values and made the following decisions when using
the PC-DEC/32 configuration notebook for Windows NT.
On the Options page none of the available check boxes were selected.
• We have two servers that are part of the sample application that must be
generated for Windows NT with DCE-based client/server communication support:
VGD2WNT and VGD3WNT. Server VGD2OS2 is called by the sample application
GUI client. Server VGD3OS2 is called by a sample application server when a
three-tier server call to an Windows NT platform using DCE-based client/server
communication is requested.
• Server VGL3WNT is generated with a local call interface. VGL3WNT can be called
by VGD2WNT to implement an alternative third tier call.
The following steps are required to build the VisualAge Generator server applications:
1. Define linkage table for DCE sample application servers. Figure 46 on page 72
shows the linkage table entries we used to generate the VGD2WNT, VGD3WNT,
and VGL3WNT applications.
Figure 46. Linkage Table for Windows NT Sample Application Servers with DCE-Based
Client/Server Communication Support. Linkage table entries for both the servers being
generated and servers that can be called from VGD2WNT are included.
You are now ready to configure and start the DCE server program on this workstation.
This process is nearly identical on OS/2, Windows NT, and AIX server platforms. For
this reason, we describe it only once in 4.2.7, “Running Applications with DCE-Based
Client/Server Communication” on page 75.
We used the following software for the Windows 95 DCE GUI Client:
• Windows 95
• VisualAge Generator GUI Run Time for Windows Version 2.2 (Fixpak 3)
To implement the DCE GUI client workstation we had to install and configure DCE. We
also generated the Windows 95 GUI client portion of the sample application. To install
DCE support on Windows 95, we did the following:
To configure RPC support with Gradient′s PC-DCE/32, you need the cell name and the
TCP/IP names or addresses of the CDS and Security server. In our configuration, we
ran the CDS, security, and DTS servers on the AIX DCE server workstation. We
provided these values and made the following decisions when using the PC-DEC/32
configuration noteboook for Windows 95.
Note: The PC-DEC/32 configuration noteboook is displayed when the Configure push
button is clicked on the DCE Service Panel. The DCE Service Panel can be started
using the PC-DCE/32 icon in the Windows 95 Control Panel.
On the Options page, none of the available check boxes were selected.
The sample application client can directly call on DCE-based server application:
VGD2OS2.
The following steps are required to build the VisualAge Generator client applications:
1. Define linkage table for all possible Windows 95 client platform calls to DCE
sample application servers. Figure 48 shows the linkage table entries we used to
generate the sample application GUI client and local C + + server to support
second- or third-tier calls to OS/2, Windows NT, or AIX platforms.
Figure 48. Linkage Table for Windows 95 Sample Application Client with DCE-Based
Client/Server Communication Support
Figure 49. Sample Application Generation Commands for Windows 95 GUI Client for
DCE-Based Client/Server Communication. Generation of embedded GUI applications will
occur because of the /GENEMBEDDEDGUIS default generation option.
Figure 50. VisualAge Generator DCE-Based Client and Application Server Configuration
Implementation requires that we first configure and then start the DCE server program
(CSODCES), learn how it interacts with the directory setup in the DCE cell, and then
start the client end of the sample application. We also study techniques for
implementing multiple application server workstation platforms for one
SERVERID/LOCATION pair.
Figure 51. DCE.CNF Configuration File for OS/2 DCE Application Server
This configuration file defines how the CSODCES program will operate. The
following parameters are defined:
DCEprincipal DCE principal that will be used for CDS access. This principal is
also defined in the DCE keytab file using rgy_edit.
DCEACLobject Name of the active access control list (ACL) object used for
secure communication (REMOTECOMTYPE=dcesecure)
The SERVERID and LOCATION values used in the CSODCES configuration file
must match the SERVERID and LOCATION values used in the linkage table
referenced at run time.
Figure 52 contains the DCE.CNF configuration file we used on our Windows NT
DCE application server workstation.
DCEprincipal=vgwntsj1
LOCATION=vgwnt
SERVERID=vgcs
DCEACLobject=/.:/Servers/VAGenerator/vgcs/vgwnt
SECURE APPLICATIONS=
PUBLIC APPLICATIONS=
VGD2WNT
VGD3WNT
Figure 52. DCE.CNF Configuration File for Windows NT DCE Application Server
DCEprincipal=vgaixsj1
LOCATION=vgaix
SERVERID=vgcs
DCEACLobject=/.:/Servers/VAGenerator/vgcs/vgaix
SECURE APPLICATIONS=
PUBLIC APPLICATIONS=
VGD2AIX
VGD3AIX
Figure 53. DCE.CNF Configuration File for AIX DCE Application Server
[E:\vgcs\dcesec]rgy_edit
Current site is: registry server at /.../vgrisc
rgy_edit=> do princ
Domain changed to: principal
rgy_edit=> ktadd -p vgos2sj1 -pw vgos2sj1
rgy_edit=> ktlist
/.../vgrisc/hosts/vgrisc.almaden.ibm.com/self 1
/.../vgrisc/hosts/vgrisc.almaden.ibm.com/self 2
/.../vgrisc/vgos2sj1 1
rgy_edit=> exit
bye.
[E:\vgcs\dcesec]
Figure 54. Adding Key Table Entry for DCE Application Server Principal
You need to add the principal to the keytab on each DCE application server
workstation you configure. The rgy_edit interface is the same regardless of
operating system environment (OS/2, Windows NT, AIX). If you reconfigure DCE
software, the keytab file is often reinitialized. This may require that you add the
principal again.
Sometimes DCE services will not start. Often, the problem is a time skew
between the workstation and the time as known to the DCE Cell. DCE can be
configured to synchronize the time on the workstation with the time as known to
the DCE Cell, which prevents this time-skew problem.
EZERSQLDB=SAMPLE
CSOLINKTBL=H:\VGCS\ACTIVE.LKG
CSOTROPT=2
FCWTROPT=31
d /.:/Servers
d /.:/Servers/VAGenerator
d /.:/Servers/VAGenerator/vgcs
Figure 55. CDS Directories for SERVERID on AIX Cell Server. The d signifies that the
entry is a directory. (We cut/paste this information from the CDS list shown in smitty.) We are
using vgcs as the SERVERID value in our DCE configuration file and linkage table.
We started the CSODCES DCE server program on the OS/2 DCE server
workstation with this command:
csodces -c vgos2.cnf
This tells CSODCES to start a primary DCE server program using the configuration
file, vgos2.cnf. See 4.2.7.4, “Implementing Multiple DCE Application Server
Workstations” on page 84 for a discussion of CSODCES startup parameters for
primary and secondary DCE server programs.
[E:\vgcs\dcesec]csodces vgos2.cnf
DCEprincipal TOKEN=vgos2sj1
LOCATION TOKEN=vgos2
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
Server to be loaded VGD2OS2.
Server to be loaded VGD3OS2.
Registering server interface with RPC runtime...
Registering server endpoints with endpoint mapper (RPCD)...
Exporting server bindings into CDS namespace...
Server /.:/Servers/VAGenerator/vgcs/vgos2 listening...
Figure 57 shows the object entries for the identified location and the available
VisualAge Generator server applications that were added to the directory
structure shown in Figure 55 on page 78.
d /.:/Servers
d /.:/Servers/VAGenerator
d /.:/Servers/VAGenerator/vgcs
o /.:/Servers/VAGenerator/vgcs/VGD2OS2
o /.:/Servers/VAGenerator/vgcs/VGD3OS2
o /.:/Servers/VAGenerator/vgcs/vgos2
Figure 57. CDS Directories and Application Objects on AIX Cell Server. The o signifies
that the entry is an object. We are using vgos2 as the LOCATION value in our DCE
configuration file and linkage table for the OS/2 DCE server workstation. VGD2OS2 and
VGD3OS2 are the names of the VisualAge Generator server applications available at this
location for the SERVERID system.
The CDS object vgos2 is used to locate the application server workstation where
the requested VisualAge Generator server applications can be found.
We can see this information as stored in the CDS object by DCE using DCE
commands (see Figure 58 on page 80).
SHOW
OBJECT /.../vgrisc/Servers/VAGenerator/vgcs/vgos2
AT 1997-02-18-19:59:22
RPC_ClassVersion = 0100
RPC_ObjectUUIDs = 80d3f926e489d0119b3708005a94dcc5
RPC_ObjectUUIDs = 602a1728e489d0119b3708005a94dcc5
CDS_CTS = 1997-02-18-23:10:23.761560100/10-00-5a-b1-f3-f8
CDS_UTS = 1997-02-19-00:45:07.281280100/10-00-5a-b1-f3-f8
CDS_Class = RPC_Server
CDS_ClassVersion = 1.0
CDS_Towers = :
Tower = ncadg_ip_udp:129.33.160.215[]
cdscp>
Figure 58. Information for a CDS Object as Shown Using cdscp. The highlighted tower
data includes the TCP/IP address for the OS/2 application server workstation.
You can log into the DCE cell, using a DCE user ID, if you want. However, this is not
required unless you have implemented secure DCE-based client/server
communication (REMOTECOMTYPE=dcesecure).
You must also set the CSOLINKTBL environment variable to identify the linkage table
file to be used for remote calls. The linkage table entries shown in Figure 44 on
page 69 or Figure 48 on page 74 are used to both generate and run the GUI
application.
Figure 59 shows the object entries for the available DCE application server
workstations and VisualAge Generator server applications.
d /.:/Servers
d /.:/Servers/VAGenerator
d /.:/Servers/VAGenerator/vgcs
o /.:/Servers/VAGenerator/vgcs/VGD2AIX
o /.:/Servers/VAGenerator/vgcs/VGD2OS2
o /.:/Servers/VAGenerator/vgcs/VGD2WNT
o /.:/Servers/VAGenerator/vgcs/VGD3AIX
o /.:/Servers/VAGenerator/vgcs/VGD3OS2
o /.:/Servers/VAGenerator/vgcs/VGD3WNT
o /.:/Servers/VAGenerator/vgcs/vgaix
o /.:/Servers/VAGenerator/vgcs/vgos2
o /.:/Servers/VAGenerator/vgcs/vgwnt
Figure 59. Application Objects for OS/2, Windows NT, and AIX DCE Application Server
Workstations
When the sample application GUI client issues a call to a DCE-based server, the
location object is used to identify the DCE application server workstation that can
satisfy the call (see Figure 58). The call, a DCE remote procedure call request, is then
passed using DCE-based client/server communication to the server platform.
Figure 60 (Part 1 of 2). VisualAge Generator Windows 95 Client Trace Log for DCE-Based Client/Server
Communication Calls
Figure 60 (Part 2 of 2). VisualAge Generator Windows 95 Client Trace Log for DCE-Based Client/Server
Communication Calls
F Return to client application with time for server call. The time required for
the first call to each target platform includes the lookup of the DCE
destination and the target platform runtime initialization. (On the OS/2
target platform, the F-1 entry includes DB2/2 database startup
processing.) The DCE target location is cached on the client so lookups
are not required for subsequent calls.
We had one CSODCES DCE server program running for each target platform
(LOCATION values: vgos2, vgwnt, and vgaix). Our testing showed that a DCE-based
VisualAge Generator server application cannot call another DCE-based server that is
located in the same LOCATION. That is, VGD2OS2 can not call VGD3OS2. When we
attempted this type of call on any target platform, the sample application hung up.
A DCE-based server can call a local server (for example: VGD2OS2 can call VGL3OS2
and VGD2WNT can call VGL3WNT).
configuration-file name
The configuration file specifies which VisualAge Generator server
applications are available (can be called) on the application server
workstation. The VisualAge Generator server applications available for one
application server workstation must be available for all other application
server workstations that are started for a given SERVERID/LOCATION pair.
16 There is a problem with VisualAge Generator V2.2 at the Fixpak 3 level. The documented default parameter (-c)
must be used to trigger primary server processing. If -c is not provided, the CSODCES program processes as if
the -d parameter was provided, which makes the -d parameter the effective default. The -d parameter, when
used, causes an error message (Could not open data file, -d).
Figure 62. Primary DCE Server Program Startup Messages. The documented default
when a startup option is not specified is -c. The -c option is specified because of a bug in
VisualAge Generator V2.2 at the Fixpak 3 level, where -d is the effective default. This problem
was reported to the IBM VisualAge Generator lab.
The startup messages for the secondary DCE server program on the second
application server workstation are shown in Figure 63.
[S:\pat\vgcs-run\dce]csodces vgos22.cnf
DCEprincipal TOKEN=vgos2sj2
LOCATION TOKEN=vgos2
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
Server to be loaded VGD2OS2.
Server to be loaded VGD3OS2.
Registering server interface with RPC runtime...
Registering server endpoints with endpoint mapper (RPCD)...
Exporting server bindings into CDS namespace...
Server /.:/Servers/VAGenerator/vgcs/vgos2 listening...
Figure 63. Secondary DCE Server Program Startup Messages. Because of a bug in
VisualAge Generator V2.2 at the Fixpak 3 level, -d is the effective default. If -d is specified, an
error message results. This problem was reported to the IBM VisualAge Generator lab.
The CDS object vgos2, used as the LOCATION value for both the primary and
secondary DCE server programs, is used to locate where the requested VisualAge
Generator server applications can be found. Using a DCE command we can see that
both workstations are identified in the information stored in the CDS object by DCE
(see Figure 64 on page 86).
SHOW
OBJECT /.../vgrisc/Servers/VAGenerator/vgcs/vgos2
AT 1997-02-21-19:14:13
RPC_ClassVersion = 0100
RPC_ObjectUUIDs = 80d3f926e489d0119b3708005a94dcc5
RPC_ObjectUUIDs = 602a1728e489d0119b3708005a94dcc5
CDS_CTS = 1997-02-20-18:05:20.371582100/10-00-5a-b1-f3-f8
CDS_UTS = 1997-02-22-00:13:25.767033100/10-00-5a-b1-f3-f8
CDS_Class = RPC_Server
CDS_ClassVersion = 1.0
CDS_Towers = :
Tower = ncadg_ip_udp:129.33.160.215[]
CDS_Towers = :
Tower = ncadg_ip_udp:129.33.160.233[]
cdscp>
Figure 64. CDS Object Information for Two Application Server Workstations. The
highlighted tower data includes the TCP/IP address for both the primary and the secondary
OS/2 application server workstations.
When multiple application-server workstations are available, the choice of which one
is used to satisfy a call is randomized. Figure 65 shows the client/server
communication trace log for a client where the same server call is resolved by two
different workstations.
<Feb 21 17:03:01>->CMCALL
<Feb 21 17:03:01> Calling application VGD2OS2
<Feb 21 17:03:01> ->readFromLinkTbl
<Feb 21 17:03:01> <-readFromLinkTbl - 0.050
<Feb 21 17:03:01> ->DCE:CMDV_CALL
<Feb 21 17:03:01> ++DCE:CMDV_CALL
<Feb 21 17:03:01> ++++DCE:CreateParmBlock
<Feb 21 17:03:01> ====0.060
<Feb 21 17:03:01> Using binding handle: 26f9d380-89e4-11d0-9b37-08005a94dcc5@ncadg_ip_udp:129.33.160.233[]
<Feb 21 17:03:01> Passing 428 bytes of data
<Feb 21 17:03:01> ++++DCE:RPCCall
<Feb 21 17:03:06> ====4.770
<Feb 21 17:03:06> ==5.160
<Feb 21 17:03:06> <-DCE:CMDV_CALL
<Feb 21 17:03:06><-CMCALL - 5.490
<Feb 21 17:03:07>->CMCALL
<Feb 21 17:03:07> Calling application VGD2OS2
<Feb 21 17:03:07> ->readFromLinkTbl
<Feb 21 17:03:07> <-readFromLinkTbl - 0.060
<Feb 21 17:03:07> ->DCE:CMDV_CALL
<Feb 21 17:03:07> ++DCE:CMDV_CALL
<Feb 21 17:03:07> ++++DCE:CreateParmBlock
<Feb 21 17:03:08> ====0.050
<Feb 21 17:03:08> Using binding handle: 26f9d380-89e4-11d0-9b37-08005a94dcc5@ncadg_ip_udp:129.33.160.215[]
<Feb 21 17:03:08> Passing 428 bytes of data
<Feb 21 17:03:08> ++++DCE:RPCCall
<Feb 21 17:03:10> ====2.630
<Feb 21 17:03:10> ==2.970
<Feb 21 17:03:10> <-DCE:CMDV_CALL
<Feb 21 17:03:10><-CMCALL - 3.240
<Feb 21 17:03:13>->CMCOMMIT
<Feb 21 17:03:13><-CMCOMMIT - 0.060
<Feb 21 17:03:13>->CMCLOSE
<Feb 21 17:03:13><-CMCLOSE - 0.000
Figure 65. Client/Server Communication Trace Log for Multiple Application Server Workstations
With the -c parameter, when the primary DCE server program CSODCES terminates, it
will remove all DCE binding information for the active SERVERID/LOCATION pair. This
means that secondary servers started to support the same SERVERID/LOCATION
would still be running, but not accessible.
The rules for running multiple copies of CSODCES that advertise for the same
SERVERID/LOCATION are these:
• Start the first (primary) DCE server with the command: csodces -c config-file
• Stop all secondary DCE servers (those started with the ′-d′ option) first
• Stop the primary DCE server (the one started with the ′-c′ option) last.
The shutdown messages for the secondary DCE server program on the second
application server workstation are shown in Figure 66.
[S:\pat\vgcs-run\dce]csodces vgos22.cnf
DCEprincipal TOKEN=vgos2sj2
LOCATION TOKEN=vgos2
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
Server to be loaded VGD2OS2.
Server to be loaded VGD3OS2.
Registering server interface with RPC runtime...
Registering server endpoints with endpoint mapper (RPCD)...
Exporting server bindings into CDS namespace...
Server /.:/Servers/VAGenerator/vgcs/vgos2 listening...
Unregistering interface from EPV...
[S:\pat\vgcs-run\dce]
Figure 66. Secondary DCE Server Program Shutdown Messages. The highlighted
statements show the secondary DCE server program removing the RPC mapping entries. This
prevents calls from being routed to a particular application server workstation. Other active
application server workstations for a given SERVERID/LOCATION pair can still process server
calls.
The shutdown messages for the primary DCE server program on the first application
server workstation are shown in Figure 67 on page 88.
[E:\vgcs\dcesec]
Figure 67. Primary DCE Server Program Shutdown Messages. The highlighted
statements show the primary DCE server program removing entries from the RPC mapping,
DCE run time, and DCE CDS. When these entries are removed, no servers can be called for a
given SERVERID/LOCATION pair.
• Explicitly permitted the required access to the base DCE directory used by the
VisualAge Generator DCE server program (/.:/Servers/VAGenerator) to the
vgservers group (see Figure 38 on page 63).
This ensured that only authorized DCE server programs could modify the directory
structure and create objects in the base directory used by VisualAge Generator
DCE-based client/server communication.
• Altered the default access for unauthenticated and any_other DCE users for the base
DCE directory used by the VisualAge Generator DCE server program (see
Figure 39 on page 64).
This prevented any users, even those not logged in to the DCE cell, from having
test authority on objects created in a SERVERID directory. The test authority is
required for sucessful REMOTECOMTYPE=dcesecure client/server communication
processing.
These changes did not implement security, but they did prepare the directory structure
so that security could be implemented.
With the appropriate DCE ACL definitions and DCE-based client/server communication
configuration file, we can implement two forms of security:
This anomaly occurs because the ACL definitions for the CDS directory structure
permitted unauthenticated users (those not logged on to any DCE Cell) read access. All
VisualAge Generator needs to support REMOTECOMTYPE=dce client/server communication
processing is read access to the objects in the SERVERID directory.
We can use the DCE acl_edit command to check the current ACL entries for the
SERVERID directory (see Figure 68).
Figure 68. Checking Existing ACL for CDS Directory with acl_edit. The ACLs for the
SERVERID directory (vgcs), those for objects created in this directory (-io option), and those for
directories created in this directory (-ic option) are shown. The authority granted to
unauthenticated users is what allows clients to call servers without logging on to the DCE Cell.
The ACL entries shown in Figure 68 define the access for the directory and any
objects or directories created in that directory. The LOCATION object created by the
DCE server program CSODCES obtains its access authority from the initial object (-ic
acl_edit option) entry. The LOCATION object has an ACL entry that matches the initial
object entry for the directory the object is created in, at the time the object is created.
Figure 69 on page 90 shows the ACL entry for the vgos2 LOCATION object created for
our OS/2 application server workstation.
Figure 69. Initial ACL Entry for LOCATION Object. The authority granted to
unauthenticated users allows clients to call servers without logging on to the DCE Cell.
To force client platforms to log on to the DCE Cell, we must restrict access to the
SERVERID directory to logged-on users. The following steps are required to restrict
VisualAge Generator application server access to logged-on client workstations:
This does not change the ACL for existing objects. ACLs for objects cannot be
directly changed. You must change the initial object ACL for the directory where
the object is to be created and then create (or recreate) the object. This leads to
our next step.
2. Stop any active DCE server programs and delete the existing LOCATION and
VisualAge Generator application server objects from the SERVERID directory.
Figure 71 contains the csccp commands used to list and then delete the existing
objects in the SERVERID directory.
vgrisc:/> cdscp
cdscp> list obj /.:/Servers/VAGenerator/vgcs/*
LIST
OBJECT /.../vgrisc/Servers/VAGenerator/vgcs
AT 1997-02-26-14:50:13
VGD2OS2
VGD3OS2
vgos2
cdscp>
cdscp> del obj /.:/Servers/VAGenerator/vgcs/vgos2
cdscp> del obj /.:/Servers/VAGenerator/vgcs/VGD2OS2
cdscp> del obj /.:/Servers/VAGenerator/vgcs/VGD3OS2
cdscp>
cdscp> list obj /.:/Servers/VAGenerator/vgcs/*
LIST
OBJECT /.../vgrisc/Servers/VAGenerator/vgcs
AT 1997-02-26-17:09:19
cdscp>
Figure 71. cdscp Commands to List and Delete SERVERID Directory Objects
This clears the old objects and their associated ACLs. We can now recreate the
objects (we let the DCE server program do this for us).
Figure 72. ACL Entry List for Location Object to Force DCE Logon
4. Test VisualAge Generator application server access without logging on to the DCE
Cell (and after logging on to to the DCE Cell)
You can use the acl_edit command to predict the success of the server call.
Since you need read access to the object, you can ask if you can in fact read the
object before logging on to the DCE Cell (see Figure 73).
[S:\pat\vgcs-run\os2]acl_edit /.:/Servers -l
Warning - you currently have no tickets
Warning - binding to ACL′ s server is unauthenticated
Warning - binding to registry is unauthenticated
[S:\pat\vgcs-run\os2]acl_edit /.:/Servers/VAGenerator -l
ERROR: acl object not found (dce / sec)
Unable to bind to object /.:/Servers/VAGenerator
[S:\pat\vgcs-run\os2]
Figure 73. Testing Directory Access for Unauthenticated DCE Users with acl_edit
Commands
Figure 74. Trace Log for Unauthenticated VisualAge Generator Server Application Call
Once a DCE cell logon has been performed, both the acl_edit commands and the
client call to the VisualAge Generator server application are successful (see
Figure 75 and Figure 76 on page 93).
[S:\pat\vgcs-run\os2]acl_edit /.:/Servers/VAGenerator -l
[S:\pat\vgcs-run\os2]acl_edit -e /.:/Servers/VAGenerator/vgcs/vgos2 -l
[S:\pat\vgcs-run\os2]
Figure 75. Testing Directory Access for Authenticated DCE Users with acl_edit
Commands
Figure 76. Trace Log for Authenticated VisualAge Generator Server Application Call
By using native DCE CDS authorizations, as defined in the directory and object ACLs,
we can implement a form of security. All client workstations must have an active
logon to the DCE Cell to call a VisualAge Generator server application.
We did not restrict who had read access to the SERVERID directory and LOCATION
object; we allowed any_other users access. We could have used a DCE group to
control who had read access and removed the ACL entry for any_other users. This
would add another level of security to the system.
By using only DCE functions, we have not added any overhead to the call of a
VisualAge Generator server application. This differs from the next technique, which
asks the DCE server program to validate that the DCE user requesting the VisualAge
Generator server application has a specific level of authority before the call is
processed.
The DCE server program uses the ACL identified on the DCEACLobject statement in the
DCE configuration file for authorization checking:
DCEACLobject=/.:/Servers/VAGenerator/vgcs/vgos2
(See 4.2.7.1, “DCE Server Program Configuration” on page 75 for a DCE configuration
file description.)
The DCE server program checks whether the DCE client making the server call has
the test (t) authority for the identified ACL object to determine if the DCE client can
have access to a secure VisualAge Generator server application.
The DCE server program CSODCES will only allow access to a secure VisualAge
Generator server application when both of the following conditions are true:
• The user′s DCE principal ID, or a DCE group that contains the principal ID as a
member, must be included as an entry in the ACL for the security object.
If we had not revised the ACL entries for our base DCE CDS directory (see 4.2.2.2,
“DCE Environment Configuration” on page 60), then test authority, and therefore
secure server access, would be allowed to these DCE users:
Our current ACL entries for the LOCATION object (see Figure 75 on page 92) do not
permit the test authority to the unauthenticated or any other DCE user categories.
Specific authorities are not permitted to any of the end user principal IDs (vguserx or
vgadx) or groups (vgusers, vgusradm) 17 we defined for our DCE-based client/server
communication environment (see Figure 34 on page 61). We are now ready to
implement active authorization checking for a configuration that permits only members
of the vgusradm group to call VisualAge Generator server applications.
To implement DCE server program authorization checking, we must provide the test
authority on the security object (defined to be the same as our LOCATION object) to
our selected set of users (the vgusradm group from Figure 34 on page 61), configure
the DCE-based client/server communication environment to use the
REMOTECOMTYPE=dcesecure linkage table option, and log on to the DCE Cell with an
authorized principal ID.
1. Add an entry for the group vgusradm to the initial object ACL for the SERVERID
directory
Figure 77 contains the acl_edit commands used to add an initial object ACL entry
to, and then list the entries for, the SERVERID directory for the vgusradm group.
Figure 77. acl_edit Commands to Permit Test Access for vgusradm Group
To change the ACL for the LOCATION object we must delete and then create the
object. This leads to our next step.
2. Stop any active DCE server programs and delete the existing LOCATION object
from the SERVERID directory
17 We do permit access to the vgservers group. This group represents DCE server program tasks. These are
permitted access to the directory structure so that location and VisualAge Generator server application objects
can be created. See Figure 38 on page 63 for details.
Figure 78. cdscp Commands to Delete LOCATION Object and then List Remaining
SERVERID Directory Objects
We deleted the the LOCATION object so that it could be recreated with a new set
of ACL entries based on the initial object ACL defined for the SERVERID directory.
3. Change the linkage table entries for DCE-based VisualAge Generator server
applications so that calls use the REMOTECOMTYPE=dcesecure communications option.
The linkage table entries for calls to the VisualAge Generator server applications
on the OS/2 application server workstation are shown in Figure 79.
Figure 79. Linkage Table for OS/2 Sample Application Servers with Secure DCE-Based
Client/Server Communication Support
These linkage table entries must be used by both the client application and the
DCE server program.
4. Define a configuration file for secure communication and restart the DCE server
program (recreates LOCATION and VisualAge Generator application server
objects in the SERVERID directory).
The startup messages for a DCE server program configured to use secure
communications are shown in Figure 80 on page 96.
The new objects created have ACLs based on the initial object entry for the
SERVERID directory /.:/Servers/VAGenerator/vgcs. The LOCATION object now has
an ACL entry that gives the vgusradm group read and test access (see Figure 81).
Figure 81. ACL Entry List for Location Object with vgusradm Group
5. Test VisualAge Generator application server access with a general user logon
and then with an administrative user logon.
When a call to a VisualAge Generator server application is made with a general
user DCE logon, the DCE server program checks whether or not the user has test
authority on the security object. Because the general users are not in the
vgusradm group, their calls fail (see Figure 82 on page 97).
Figure 82. Trace Log for Rejected Authenticated VisualAge Generator Server Application Call
Once an administrative user logon has been performed, the client call to the
VisualAge Generator server application is successful (see Figure 83).
<Feb 28 16:24:09>->CMCALL
<Feb 28 16:24:09> Calling application VGD2OS2
<Feb 28 16:24:09> ->readFromLinkTbl
<Feb 28 16:24:09> <-readFromLinkTbl - 0.050
<Feb 28 16:24:09> ->DCE:CMDV_CALL
<Feb 28 16:24:09> ++DCE:CMDV_CALL
<Feb 28 16:24:09> ++++DCE:CreateParmBlock
<Feb 28 16:24:09> ====0.060
<Feb 28 16:24:09> Using binding handle: 0ab5fbc0-9026-11d0-9956-08005a94dcc5@ncadg_ip_udp:129.33.160.215[1066]
<Feb 28 16:24:09> Passing 428 bytes of data
<Feb 28 16:24:09> ++++DCE:RPCCall
<Feb 28 16:24:13> ====3.840
<Feb 28 16:24:13> ==4.180
<Feb 28 16:24:13> <-DCE:CMDV_CALL
<Feb 28 16:24:13><-CMCALL - 4.510
Figure 83. Trace Log for Accepted Authenticated VisualAge Generator Server Application Call
You cannot control execution authority for a specific VisualAge Generator server
application. You can only control access to the set of SECURE applications accessed
through a DCE server program.
This means that when you are permitted test access to the security object for a DCE
server program (for example DCEACLobject=/.:/Servers/VAGenerator/vgcs/vgos2), you can
call all VisualAge Generator server applications defined as secure applications in the
active CSODCES configuration file (as well as all the public applications). If you need
to restrict access to some VisualAge Generator server applications, configure them as
part of a separate LOCATION and DCE server program.
Situation and Resolution The user ID and password used did not have the required
authority. Grant authority to access the object or execute
the package.
Table 5 (Page 1 of 2). Common Problems Encountered During DCE Setup and Configuration
Error Message / Situation and Resolution
Error:
OS/2 DCE Client startup failure. Messages included text like this:
•E:\vgcs\dce‘csodces dce.cnf
DCEprincipal TOKEN=vgos2sj
LOCATION TOKEN=vgos2srv
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2srv
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
Server to be loaded VGD2OS2.
•E:\vgcs\dcesec‘csodces -c dce.cnf
DCEprincipal TOKEN=vgos2sj1
LOCATION TOKEN=vgos2
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
CSODCES.EXE: error in cso2dce_s.c•494‘:
Requested key is unavailable (dce / sec).
•E:\vgcs\dce‘csodces dce.cnf
DCEprincipal TOKEN=vgos2sj
LOCATION TOKEN=vgos2srv
SERVERID TOKEN=vgcs
DCEACLOBJECT TOKEN=/.:/Servers/VAGenerator/vgcs/vgos2srv
SECURE APPLICATIONS =
PUBLIC APPLICATIONS =
VGD2OS2
VGD3OS2
Server to be loaded VGD2OS2.
CSODCES.EXE: error in cso2dce_s.c•590‘:
No permission for name service operation (dce / rpc).
<Feb 12 13:49:00>->CMINIT
<Feb 12 13:49:01><-CMINIT - 0.058374 s
<Feb 12 13:49:01>->CMCALL
<Feb 12 13:49:01> Calling application VGD2AIX
<Feb 12 13:49:01> ->readFromLinkTbl
<Feb 12 13:49:01> <-readFromLinkTbl - 0.215518 s
<Feb 12 13:49:01> ->loadAndInitDriver
<Feb 12 13:49:02> <-loadAndInitDriver - 0.946563 s
<Feb 12 13:49:02> ->CMDV_INIT
<Feb 12 13:49:02> <-CMDV_INIT - 0.025085 s
<Feb 12 13:49:02> ->DCE:CMDV_CALL
<Feb 12 13:49:02> ++DCE:CMDV_CALL
<Feb 12 13:49:02> ++++DCE:CreateParmBlock
<Feb 12 13:49:02> ====0.062557 s
<Feb 12 13:49:03> ERROR REASON CODE: 7801, Message: CSO7801E
An error was encountered while performing DCE API call rpc_ns_binding_import_next.
The DCE error string is No more bindings (dce / rpc).
Distributed presentation
The user interface is available in a remote session. CICS terminal or
X-Window sessions are two examples of distributed presentation.
Remote presentation
The user interface exists on the client platform while application processing
runs on a remote platform. This is a thin client approach because much of
the application runs off the client workstation.
Distributed function
The user interface and some application processing occurs on the client
platform and the remaining application processing runs on a remote
platform. This is a heavier client with shared logic on the server.
Remote data
The user interface and all application processing occur on the client
platform but the database accessed is on a remote platform. This is a fat
client approach because most of the application runs on the client
workstation.
Distributed data
The user interface and all application processing occurs on the client
platform. Multiple databases are accessed. Databases are either a mix of
local and remote or all remote. This approach is often seen as including
support for updates to multiple databases in a single logical unit of work.
Note: These are simplified definitions. What makes it all more complex is that you
can mix and match portions of each approach in any given system. You may call a
server (remote presentation or distributed function) and the server may implement a
form of remote or distributed database access.
While VisualAge Generator provides support for all of the client/server approaches
defined above, we focus this chapter on the use of database technology. We review
supported approaches to remote and distributed database access and discuss the
implementation of VisualAge Generator applications that access relational databases
in local, remote, and distributed environments.
DB2 Common Server technology provides both stand-alone and networked relational
database support. Connecting different installations of DB2 Common Server
technology is very easy to do even when they are running on different workstation
hardware and software platforms.
Figure 84 shows the DB2 client platforms that can be connected to other DB2
Common Server installations.
• It is necessary to limit the amount of data that is passed to and from the
application and the remote DB2 server.
Figure 85 shows the DB2 client platforms that can be connected to DB2 host platforms
using DRDA support.
Technically, you can use DRDA connections between DB2 Common Server
workstations, but this is not recommended in most scenarios because of the additional
software and configuration tasks required.
5.1.3 DataJoiner
Data Joiner is a an enhanced DB2/6000 that is able to catalog non-IBM relational
databases. Before implementing an application system using DataJoiner, careful
examinations of compatibility and performance issues are strongly recommended.
This section describes the basic requirements for a working database configuration for
VisualAge Generator development and runtime environments and then discuss the
new support provided by VisualAge Generator Version 2.2 for distributed unit of work
(DUOW) support.
Configuring VisualAge Generator for database access is very well documented in the
Running VisualAge Generator Applications on OS/2, AIX, and Windows manual. In this
section, therefore, review only the basic requirements for a functioning database
connection.
Connecting to a local database, one that exists on the same workstation as the
VisualAge Generator Developer or generated application, is straightforward. All you
need to do is identify the database name.
When you need to connect to a host database, you need the appropriate DDCS
software and communications configuration to support a DRDA-based connection.
• Provide support for the selected communication protocol (TCP/IP, NetBIOS, APPC,
IPX).
• Catalog the remote node.
• Catalog the remote database.
• For DRDA connections, you also need to catalog the DCS database.
Remote database configuration steps are documented in the appropriate DB2 and
DDCS product manuals. For additional guidance, you might want to review Distributed
Relational Database Cross Platform Connectivity and Applications .
Access to any DB2 relational base typically works if these statements are functional
for your target database and a table in your database environment:
The success of the connect statement depends on the availability of a valid database
logon or authorization ID.
For remote databases, the active local or LAN logon, if available, will be used for
authorization processing unless you have logged on directly to the remote database
node with a node logon:
VisualAge Generator applications will use the local, node, or LAN logon for connecting
to the target DB2 environment. EZECONCT statement processing can use the active
DB2 authorization ID or include user ID and password values as part of the explicit
connection request. This is discussed further in 5.2.2.3, “Connecting to Multiple DB2
Databases” on page 114.
Several environment variables are also available to identify the database that to be
used during development, run time, or both. These environment variables are used in
this order, depending on target runtime environment (if the aim is development, the
runtime environment variables do not apply unless generated applications are called
by ITF):
This is only the setting in the active OS/2 window. Global settings must be defined
in the CONFIG.SYS file.
When a database is defined for a generated application using the available VisualAge
Generator environment variables, the implicit database connection identifies the
database being used. Subsequent database access uses this active database unless
an alternative database is selected using the EZECONCT statement in the VisualAge
Generator application logic.
The active setting of the database environment variables used by VisualAge Generator
generated C + + applications and the resulting use of an implicit database connection
is visible in the trace logs shown in Figure 87 through Figure 88 on page 110.
Figure 88. Trace of Implicit DB2DBDFT Database Connection and Database Access.
The implicit database connection shown (where the DB2DBDFT environment variable was used
to identify the active database name) looks the same as the log file shown in Figure 89 on
page 110. The only difference is that the subsequent database access succeeds because a
default database was identified.
Figure 89. Trace of Implicit Database Connection and Database Access Failure. When
no database is defined for a generated application using the available environment variables,
the implicit database connection will execute successfully, but any subsequent database access
will fail.
Notes:
1. The implicit database connection does not occur when testing an application using
ITF. A database connection, based on the VisualAge Generator Developer
database profile or the EZERSQLDB environment variable setting, is made only when
an SQL statement is about to be processed. This restriction can affect the use of
the EZECONCT statement in application logic. If you reset a database connection
or query the current status of an existing connection, the response encountered
during ITF may differ from that for runtime processing. This possibility should be
factored into both application design and testing.
2. A possible change to make VisualAge Generator V2.2 work like V2.0 may be made
by development staff. The refresh level (Fixpak 2) of VisualAge Generator V2.2
issues a request to start the database manager and to make the default database
This section explains the database connection requirements, design issues, and
describes a sample application that implements DUOW programming support. A full
description of the DUOW sample application is provided in A.2, “DUOW Sample
Application” on page 168.
During our study, we relied upon the volume Distributed Relational Database Cross
Platform Connectivity and Applications for guidance on implementing database
connections.
With distributed unit-of-work support as provided by the DB2 product set and the
enhancements to the EZECONECT statement as provided by VisualAge Generator Version
2.2, one VisualAge Generator application can:
Full details for the syntax of the EZECONCT statement are available in the volume
Designing and Developing VisualAge Generator Applications and the VisualAge
Generator Developer help facility.
DUOW processing with the EZECONCT statement is supported during ITF processing
and by generated C + + applications in these environments:
• OS/2
• Windows NT
• AIX
• CICS/NT
• CICS/6000
To implement DUOW processing with the EZECONCT statement, you can use these
versions of DB2:
UOW = R
UOW = DCURRENT (implemented as RESET)
U OW = D AL L (implemented as RESET)
The middleware processing for the listed database functions is also used by ITF in
VisualAge Generator V2.2. This allows for a coordinated commit between GUI and
non-GUI applications running in an ITF environment and calls to local OS/2 generated
C+ + applications (as implemented by ITF when using a linkage table).
• For the best performance, have all transactions in the CICS region use the default
database.
On OS/2 with DB2/2, we used the Client Setup icon to start the configuration program.
Using the Client and then Configure... menu options we started the client configuration
dialog. The transaction manager database is defined on the Logging notebook page
of the client configuration dialog. We tested our sample DUOW application using both
available transaction manager database choices:
Other This sets the transaction manager database to the database identified in
the transaction-manager database entry field.
The choice of a transaction manager database can affect database naming, and
connection configuration as well as application programming rules. Note that the
transaction manager database cannot be accessed using DRDA protocols.
The database connect statement can include a user ID and password for the database
logon to be used for authorization checking:
This allows you to specify the authorization ID that will be used by DB2 instead of
using a local or LAN logon identifier. This is important, as the target databases can
require different authorization IDs and passwords. In some environment, the IDs and
passwords can be case sensitive.
VisualAge Generator implements the EZECONCT statement using DB2 CONNECT TO DATABASE
processing. When you use the VisualAge Generator EZECONCT statement to explicitly
connect to a database, user ID and password values are passed as part of the
request.
With explicit database connections implemented using the EZECONCT statement, there
are two basic requirements:
1. You must have a valid local, LAN, or node logon to satisfy the implicit database
connection performed by the VisualAge Generator application at startup (or when
called).
If a valid logon is not available, a local logon prompt dialog is shown.
2. You must provide a user ID and password value that is valid for the target
database.
This user ID or password data can be hard coded in the application EZECONCT
statement or be derived from the active local, LAN, or node logon.
You can cancel the VisualAge Generator-triggered local logon prompt dialog requests
and still get an application that uses EZECONCT statements to access a database
successfully but this is not practical in an operational environment:
• If the VisualAge Generator application that accesses the database runs on the
end-user′s workstation, the end-user must cancel every logon request triggered
by an implicit database connect
This means that you need some form of active logon to support the implicit database
connection that occurs in all VisualAge Generator applications that access a relational
database—even those that use the EZECONCT statement to manage database
connections with user ID or password parameters supplied by the application logic.
This means that to run a DUOW application you still need a valid logon, but you can
avoid an actual database connection by not setting any of the environment variables
that are used to identify the active relational database (see 5.2.1.4, “Identifying the
DB2 Database” on page 108). A valid connection must be established before SQL
processing can be performed.
If you implement more than one database in your local DB2/2 environment, you can
issue EZECONCT statements to switch between them during ITF processing. The
completed application, when generated, can access multiple local databases, a mix of
local and remote databases, or multiple remote databases.
Before you use the EZECONCT statement in an application, you should test that you
can issue DB2 CONNECT TO database statements from the command line in your OS/2
development environment. Once connected to the target database, with the
appropriate authority, you should issue a DB2 SELECT ... statement to validate access
authority.
By first using DB2 command line processing to test your database connections you
reduce the complexity of resolving problems. The DB2 Database Director program is
also useful for ensuring that connections and authorities are functioning appropriately.
There are several issues to consider when using ITF to test applications that use
EZECONCT statements to manage database connections:
• Do not define a current ID for use as the table qualifier in the VisualAge
Generator Developer database preferences profile.
Using a current ID value in the database preferences profile works fine when you
are connecting to an MVS database and want to use unqualified table names in
your VisualAge Generator SQL record definitions. If you are using a local
database, the value is ignored for standard SQL activity.
The problem arises when you are using DUOW processing. There seems to be a
bug because the first EZECONCT statement, whether a connect or a disconnect,
triggers an SQL error code of -900. If the same logic is run a second time without
stopping the test cycle, it succeeds.
A full description of the DUOW sample application is provided in A.2, “DUOW Sample
Application” on page 168. This section reviews the configuration of the DUOW sample
application, including the remote database connections, for selected development and
runtime environments.
In this section, we quickly review the environment we used to validate the use of
remote and distributed database access as implemented in the DUOW sample
application. Configuration comments are made, but they may not be sufficient as a
guide for you to complete a full distributed database configuration.
We used many configurations and hardware platforms during our study to test different
methods of implementing database access.
DB2/2, DB2/6000, and DB2/MVS environments were connected using the connectivity
functions of DB2 common server, and for the MVS target, DDCS/2.
We used TCP/IP as the protocol for DB2 common server connections. This was very
simple to implement and provided sufficient function for our needs. You should
evaluate the benefits and limitations of each of the available DB2 common server
connection protocol options when designing your distributed database environment.
[C:]ping vgrisc.raleigh.ibm.com
PING vgrisc.raleigh.ibm.com: 56 data bytes
64 bytes from 9.67.172.228: icmp_seq=0. time=313. ms
SET DB2COMM=NPIPE,TCPIP
For an AIX workstation, you need to update the DB2COMM environment variable
in the db2profile file stored in the sqllib directory.
4. Add DB2 server service name to client and server TCP/IP services files.
Our client workstation can connect to several databases using DB2 common
server TCP/IP based communication. The services file for our client workstation
contains service name entries for each connected DB2 common server platform:
Note: The interrupt port services entry is required only when you need to support
DB2 V1.x client connections.
1 record(s) selected.
We have loaded the name field in our multiple instances of the staff table with a
value that helps us know which database we have accessed (see 5.2.3.4, “Staff
Tables” on page 123).
We repeated the process of cataloging DB2 common server nodes and databases
based on the distributed database network shown in Figure 91 on page 117.
The node and cataloged database configuration, as seen from the Node Directory
provided by the Database Director shown in Figure 92 along with System Database
Directory detail views on the client workstation (HECATE).
Figure 92. Distributed Database Nodes and Cataloged Databases. Both local and r e m o te
databases are shown in the System Database Directory detail view. We used the local
databases for DUOW testing with VisualAge Generator Developer. You can also see an entry
for an MVS database. Setting up a connection to an MVS database using DRDA is reviewed in
5.2.3.3, “DB2 DRDA Connections” on page 120.
We then connected to the DB2/2 system using a DB/2 client. This provided a shared
gateway to DB2/MVS as shown in Figure 93.
The key tasks in creating an APPC-based DRDA database connection are these:
• Configuration includes an LU6.2 session between the local logical unit (LU)
and the partner LU and common programming interface for communications
side information for the connection.
Figure 94 on page 121 shows the CM/2 network definition file (NDF) used to
support our DRDA connection to DB2/MVS.
DEFINE_LOGICAL_LINK LINK_NAME(HOST0001)
DESCRIPTION(Connection to the USIBMNR Network)
FQ_ADJACENT_CP_NAME(USIBMNR.NRMCMC1 )
ADJACENT_NODE_TYPE(LEN)
DLC_NAME(IBMTRNET)
ADAPTER_NUMBER(0)
DESTINATION_ADDRESS(X′40002042045104′)
ETHERNET_FORMAT(NO)
CP_CP_SESSION_SUPPORT(NO)
SOLICIT_SSCP_SESSION(YES)
ACTIVATE_AT_STARTUP(YES)
USE_PUNAME_AS_CPNAME(NO)
LIMITED_RESOURCE(USE_ADAPTER_DEFINITION)
LINK_STATION_ROLE(USE_ADAPTER_DEFINITION)
MAX_ACTIVATION_ATTEMPTS(USE_ADAPTER_DEFINITION)
EFFECTIVE_CAPACITY(USE_ADAPTER_DEFINITION)
COST_PER_CONNECT_TIME(USE_ADAPTER_DEFINITION)
COST_PER_BYTE(USE_ADAPTER_DEFINITION)
SECURITY(USE_ADAPTER_DEFINITION)
PROPAGATION_DELAY(USE_ADAPTER_DEFINITION)
USER_DEFINED_1(USE_ADAPTER_DEFINITION)
USER_DEFINED_2(USE_ADAPTER_DEFINITION)
USER_DEFINED_3(USE_ADAPTER_DEFINITION);
DEFINE_LOCAL_LU LU_NAME(NRRG1I00)
DESCRIPTION(Local LU)
LU_ALIAS(NRRG1I00)
NAU_ADDRESS(INDEPENDENT_LU);
DEFINE_PARTNER_LU FQ_PARTNER_LU_NAME(USIBMNR.NRARDSNB )
DESCRIPTION(DSNB on CARMVS1 - DB2 3.1)
PARTNER_LU_ALIAS(NRARDSNB)
PARTNER_LU_UNINTERPRETED_NAME(NRARDSNB)
MAX_MC_LL_SEND_SIZE(32767)
CONV_SECURITY_VERIFICATION(NO)
PARALLEL_SESSION_SUPPORT(YES);
DEFINE_PARTNER_LU_LOCATION FQ_PARTNER_LU_NAME(USIBMNR.NRARDSNB )
DESCRIPTION(DSNB on CARMVS1 - DB2 3.1)
WILDCARD_ENTRY(NO)
FQ_OWNING_CP_NAME(USIBMNR.NRMCMC1 )
LOCAL_NODE_NN_SERVER(NO);
Figure 94 (Part 1 of 2). Communications Manager Network Definition File for DRDA
Connection
DEFINE_MODE MODE_NAME(QPCSUPP )
COS_NAME(#CONNECT)
DEFAULT_RU_SIZE(NO)
MAX_RU_SIZE_UPPER_BOUND(1024)
RECEIVE_PACING_WINDOW(7)
MAX_NEGOTIABLE_SESSION_LIMIT(32767)
PLU_MODE_SESSION_LIMIT(64)
MIN_CONWINNERS_SOURCE(32)
COMPRESSION_NEED(PROHIBITED)
PLU_SLU_COMPRESSION(NONE)
SLU_PLU_COMPRESSION(NONE);
DEFINE_DEFAULTS IMPLICIT_INBOUND_PLU_SUPPORT(YES)
DEFAULT_MODE_NAME(BLANK)
MAX_MC_LL_SEND_SIZE(32767)
DIRECTORY_FOR_INBOUND_ATTACHES(*)
DEFAULT_TP_OPERATION(NONQUEUED_AM_STARTED)
DEFAULT_TP_PROGRAM_TYPE(BACKGROUND)
DEFAULT_TP_CONV_SECURITY_RQD(NO)
MAX_HELD_ALERTS(10);
DEFINE_CPIC_SIDE_INFO SYMBOLIC_DESTINATION_NAME(NRARDSNB)
DESCRIPTION(CPIC side info for DB2 v3.1 om CARMVS1)
PARTNER_LU_ALIAS(NRARDSNB )
MODE_NAME(IBMDB2LM)
SNA_SERVICE_TP_NAME(X′ 0 7 ′ , 6 DB);
Figure 94 (Part 2 of 2). Communications Manager Network Definition File for DRDA
Connection
The CM/2 configuration process is reviewed in the manual Installing and Using
OS/2 Clients . You may find the guidance available in DB2 for MVS Connections
with AIX and OS/2 helpful in when performing this task.
a. Define a remote database node for the DB2/MVS target database using APPC
support. The Database Director Node Directory Entry catalog dialog or a
command can be used to catalog the remote node. We used this command:
You may wish to automate the node logon to provide easier support for remote
database connections. This command could be added to your startup.cmd file to
automate the node logon:
You may have other local or LAN logons that are also required to support access
to local databases or to shared resources.
7 record(s) selected.
7 record(s) selected.
7 record(s) selected.
Figure 95 (Part 1 of 2). Staff Table Definitions for Distributed Database Environment
7 record(s) selected.
7 record(s) selected.
7 record(s) selected.
Figure 95 (Part 2 of 2). Staff Table Definitions for Distributed Database Environment
The staff table can be implemented in workstation environments using either the
VisualAge Generator provided d:\ezerdev2\samples\staff.IXF database export file or
the DB2SAMPLE command provided with DB2/2 V2.1. The sample database can also
be implemented on a host using the required utility commands.
To make testing easier, we loaded a specific record in each STAFF table instance, to
confirm which target database had been accessed during DUOW sample application
processing
Figure 97 contains the generation commands we used to generate the DUOW sample
application GUI and called application for use in an OS/2 environment.
Figure 97. Generate Statements for DUOW Sample Application. The default VisualAge
Generator options /GENTABLES and /GENEMBEDDEDGUIS ensured that when we generated
DUOWGUI, the VisualAge Generator table and embedded GUIs were also generated.
During preparation, our DUOWAPP application was bound against only one database.
Before we run the application against other database targets we have to bind the
application once for each database. We use this bind statement when binding against
local or remote database targets:
Figure 98 shows the basic database activity for the DUOW sample application. (The
DUOW sample application is reviewed in detail in A.2, “DUOW Sample Application” on
page 168.)
Else Double Database Access Requested (Distributed Unit of Work Database Access)
-> Connect to Target Database 1 - Type D2A (Disconnect after commit)
-> Process SQL Request
-> Connect to Target Database 1 - Type D2A (Disconnect after commit)
-> Process SQL Request
-> Commit (Triggers disconnect)
End
Exit
db2start
The active local logon ID (USERID) had the required DB2 authority to bind programs to
the target databases.
The DUOW sample application can now be tested in an ITF or native OS/2 runtime
environment. We ran the standard test set (Figure 99 on page 127) using both of
these runtime environments. We used different environment variable and
database-preference profile settings:
Figure 101 on page 129 shows a portion of the FCWTRACE.OUT file for a test run
where user ID and password data was not used as part of the EZECONCT statement.
SQL1246N
Connection settings cannot be changed while connections exist.
The Type R connection still existed—it had not been reset. When a Type R
connection request follows a Type D2A, as performed in our DUOW sample
application, there is no need to disconnect. The Type D2A connection forces an
automatic disconnect after an SQL commit or rollback.
An SQL error was received when the local logon was not authorized to perform
the SQL requests:
SQL0551N
<authorization-ID> does not have the privilege to perform operation
<operation> on object <name>.
This tells us we can write applications that do not used hard-coded user ID and
password information in the EZECONCT statements if we ensure that a user
logon is available for use as the database authorization ID (see 5.2.1.3,
“Identifying the Database Authorization ID” on page 107 for more details).
If we did not have an active local or database node logon, we could still run the
generated application, and it would work, but we had to constantly cancel local
logon request dialogs.
Even though the DUOW sample application was configured to use hard-coded
user ID and password values for the SQL connect processing, the use of SQL in
the application triggered a logon request. Canceling the logon dialog did not
affect the DUOW sample application processing.
So far, using just local databases, we see that VisualAge Generator applications that
use the EZECONCT statement can be written to use either existing local logons or
hard-coded user ID and password data for database authorization checking.
The rules are the same as when using the DB2 command line-processor interface.
You can issue DB2 CONNECT TO datbase_name requests which will use the local (or node)
logon. If not available, a logon request dialog is shown. You can also pass the
required user ID and password data as part of the DB2 command line processor
request:
To prepare to run the generated version of the DUOW sample application in the
configuration shown in Figure 91 on page 117 we bound the DUOWAPP application to
the DB2AIXSM database (we had already bound to the SAMPLE database) using this
command:
The active local logon ID (USERID) did not have the required DB2 authority to bind
programs to this remote target database. We were prompted to log on to the remote
database node (DB2AIX, see Figure 92 on page 119); once the log on was completed,
the bind finished successfully.
We now have a local and a remote node logon active on the system.
The DUOW sample application can now be tested in an ITF or native OS/2 runtime
environment. We ran the standard test set (Figure 99 on page 127) for the native
OS/2 runtime environment; a reduced test set was used to prove that the ITF could
perform all required tasks.
• Local and node logons are used to establish database authorization for the target
databases. The user ID and password values used in the EZECONCT statement
parameters are left blank.
• No logon exists for any of the target databases. User ID and password values are
provided in the EZECONCT statement parameters to identify database
authorization.
Figure 102 on page 132 shows a portion of the FCWTRACE.OUT file for a test run
where user ID and password data was passed as part of the EZECONCT statement.
Figure 102. FCWTRACE.OUT File for Distributed Access to Local and Remote Databases
The first configuration used two remote DB2/2 databases where each was on a
separate node (see Figure 103). We used the same client platform as before where
we had a full DB2/2 installed with client and local database support.
Figure 103. DUOW Configuration with Two Remote DB2/2 Databases on Different
Nodes
To prepare to run the generated version of the DUOW sample application in the
configuration shown in Figure 103, we bound the DUOWAPP application to the
DB2SJCSM and DB2RTPSM databases using these commands:
The active local logon ID (USERID) had the required DB2 authority to bind programs to
the target database on both platforms because:
The generated version of the DUOW sample application can now be tested for this
configuration.
We ran the standard test set (Figure 99 on page 127) with the generated code. Our
testing focused on these issues:
• While DB2/2 does not have to be started on the local workstation to access
remote databases, it must be started there if you use a VisualAge Generator
application to access the remote database.
The called VisualAge Generator application starts DB2/2 for you if it is there to be
started. VisualAge Generator does not know whether you intend to use local
databases, so DB2/2 is started regardless of your intent to process SQL
statements. 18
The second configuration used remote DB2/2 and DB2/6000 databases where each
was on a separate node (see Figure 104). We used a client platform where we had
DB2/2 installed with these features:
Figure 104. DUOW Configuration with Remote DB2/2 and Remote DB2/6000 Databases
on Different Nodes
The DUOW sample application can now be tested in an ITF or native OS/2 runtime
environment. We ran subsets of the standard test set (see Figure 99 on page 127)
using both of these runtime environments. Our tests focused on:
• The use of databases with different environment variable and preferences profile
settings
18 VisualAge Generator generated applications seem to issue a start database request when first called and a
database connection request (we have termed this the implicit database connection ) for each call. This imposes
overhead that, currently, cannot be avoided. The best you can do is not define a default database, using the
EZESQLDB or FCWDBNAME_appl environment variables, when you will be using EZECONCT statements to control
database access for all your SQL processing. The IBM VisualAge Generator development lab is considering
alternatives that may reduce the initial cost of calling VisualAge Generator applications. Review the readme
documentation provided with FixPak 4 for details.
The third configuration used remote DB2/2 and DB2/MVS databases where each was
cataloged on the same node (see Figure 105). We used the client platform where we
had installed DB2/2 CAE support.
Figure 105. DUOW Configuration with Remote DB2/2 and Remote DB2/MVS Databases
Cataloged on the Same Node
The DUOW sample application can now be tested in an ITF or native OS/2 runtime
environment. We ran subsets of the standard test set (Figure 99 on page 127) using
both of these runtime environments. Our tests focused on local and node logon
requirements.
• A local logon is not required to access the remote databases if the user ID and
password values are used in the EZECONCT statement parameters. This is
because we were using a client workstation that had only DB2 client application
enabler (CAE) installed.
If we did not pass the user ID and password values in the EZECONCT statement
parameters, we were prompted for node logon.
• Confusion resulted when we ran the DUOW sample application against two
databases, cataloged on the same node, that did not share a common database
authorization ID. The user ID and password used for each database was different;
a single node logon was not valid for both targets. Although UPM did allow us to
log on to the same node twice, with different user ID and password values, the
DUOW sample application could not successfully access both databases without
hard coding the required user ID and password data in the EZECONCT statement.
If we did not pass the user ID and password in the EZECONCT statement, we
would be prompted for multiple logons to the same node. It seemed as though
the last node logon was current, and each test cycle forced a logon to the node
Note: DUOW processing requests, both SQL SELECT and UPDATE, succeeded
against all other remote database pairs that we tested. As far as we could tell,
the problem (SQL30090N) was with our database configuration and not the
VisualAge Generator DUOW sample application design or preparation process.
DBCS application design and development issues are discussed in detail in Designing
and Developing VisualAge Generator Applications , SH23-0228.
When an operating system provides support for a DBCS code page environment, the
tools, products, or applications running on the operating system must be at least
DBCS-enabled in order to support DBCS data storage and display.
There are three areas where DBCS implementation issues are visible: code page,
data storage in files or databases, and I/O devices. Code pages issues are different
for each supported language DBCS. Some computing platforms have multiple code
pages for the same language.
In some language environments, there are two choices for DBCS support at the
operating system level:
IBM provides operating systems and other products that are designed to support
application development and operation in DBCS code page environments.
VisualAge Generator is a DBCS-enabled product in that you can build applications that
support DBCS code pages. VisualAge Generator is also translated into several DBCS
languages:
• Japanese
• Chinese
• Korean
The only exception is the tool used to provide online access to product manuals. The
READIBM.EXE program, which is based on the BookManager product and delivered as
an installable program with VisualAge Generator, needs special treatment when used
in a DBCS-enabled operating system.
To identify the active code page, you can enter the chcp command at an OS/2
command prompt.
To change the active code page and use the READIBM.EXE to view online manuals,
enter these commands at an OS/2 command prompt:
chcp 437
readibm
The READIBM.EXE will display a list of books and book shelves that are found using
the current setting of the READIBM environment variable.
VisualAge Generator data-item definition provides two data types that support DBCS
application requirements:
DBCS Data item can contain only double-byte characters; each single character is
represented by 2 bytes of storage.
Mix Data item can contain both DBCS and SBCS data.
When a data item can contain both SBCS and DBCS data, special considerations
apply. In an EBCDIC environment, special shift-out (SO) and shift-in (SI) characters
are used to identify the start and end of DBCS strings in a mixed data-type field. The
SO and SI characters add to the length of the data stored in a field. SO and SI
characters are not required in an ASCII environment.
The length of data items should be defined to allow for the inclusion of these special
characters in an EBCDIC environment. In a client/server system, if a MIX or DBCS
data type field is used in both an ASCII and EBCDIC runtime environment, the addition
of the SO and SI characters may make the string in the field longer in EBCDIC. You
must consider the length of mixed data fields and data items during design and
implementation so that space is reserved for the SO and SI characters.
For example, if you decide that the maximum number of characters in the DBCS
data-type field ′NAME′ will be 10, then the DB2 column in EBCDIC should be defined
as GRAPHIC(12) to allow for SO and SI characters. If the data item is to be defined
DBCS-enabled device types must be defined for map definitions in applications that
provide 3270-type displays or support printing of DBCS data. For example:
When importing a table originally created on a system with a different code page (and
then exported), you may have to use the forcein import parameter to bypass code
page conversion.
Try changing the code page (chcp command) before using database import and export
commands or use the appropriate DB2 utility options to manage database import and
export processing.
Unless specified, the steps discussed for setup are also suitable for SBCS code page
environments.
Client Workstation
Hardware:
Type PC 750-P100
Hard drive 2.0 GB
RA MB 48 MB
Network Adapter 16/4 Token Ring Card
Software:
Hardware:
Type PS/2 95
Hard drive 1.0 GB
RAM 32 M B
NetWork Adapter 16/4 MCA Token Ring Card
Software:
Host Platform
Hardware:
Not applicable
Software:
The host session was configured to support DBCS application preparation using
the command cspcmds nls(P). The cspcmds command is a customized CLIST to
allocate the correct set of APVFILEs required for DBCS file transfer.
The DBCS sample application GUI called a server running on either CICS OS/2 or
MVS CICS. This server updated the DB2 sample table STAFF.
The definition for the standard DB2 sample table (STAFF) was modified to provide
support for DBCS data in two different columns. The NAME column was defined with
support for variable-length graphic data (pure DBCS characters). The JOB column
was defined so that it could contain both DBCS and SBCS character data. Figure 108
contains the definition of the DBCS-enabled staff table.
We used the create statement shown in Figure 109 on page 145 to create the STAFF
table on the DB2 MVS system.
The VisualAge Generator record definition for the STAFF table used a data type of
DBCS for the NAME data item and MIXED for the JOB data item.
For a typical application development effort, environment you should consider using
separate workstations for development, generation, and CICS OS/2. Many of the steps
we performed are similar to those described in 3.2.1, “CICS OS/2 Server” on page 29
and 3.2.3, “CICS Client” on page 44. Unless specified, the following customization
steps are same as for other client/server configurations.
We made the following change to the OS/2 CONFIG.SYS file on the server workstation
to configure our target COBOL language system:
SET LANG=ZHCN1381
The default setting was ENUS437. A setting of ZHCN1381 provides support for
Simplified Chinese.
SET CSOLINKTBL=C:\WORKTMP\WORKDIR\LNKTBL.TBL
SET CSOUEXIT=CSOPRMPT
SET CSOTROPT=2
SET CSOTROUT=C:\WORKTMP\TRACE.OUT
SET CSOTIMEOUT=60
The CSOUEXIT setting identifies the exit we use to manage user ID and password
identification and authentication. The CSOPRMPT exit uses a GUI window to prompt
for the user ID and password values. These are passed to CICS as part of the server
call through the CICS Client ECI interface.
The EZERSQLDB setting identifies the default database name that will be used when
SQL requests are processed using VisualAge Generator Developer or generated
VisualAge Generator applications.
SET CICSWRK=C:\WORKTMP
SET EZERSQLDB=SAMPLE
The CICSWRK setting identifies the directory CICS OS/2 will use to find program
executables.
VisualAge Generator applications are generated on the server workstation. The same
linkage table must be accessible by (or replicated on) both the client and server
workstations. The client workstation uses the linkage table to determine what kind of
call to make and whether data conversion is required. The server workstation uses
the linkage table during VisualAge Generator application generation.
os2_install_drive = ′ C:′
ela_install_drive = ′ C:′
cics_install_drive = ′ C:′
cobol_install_drive=′ C:′
ela_install_dir =′ \VGWGS2′
cics_install_dir = ′ \CICS300′
cobol_install_dir = ′ \IBMCOBOL′
default_ezernls=′ CHS′
default_database =′ ′
ela_bit_mode=′ 3 2 ′
ela_cics_group=′ VGWGS′
cics_version=′ 3 . 0 ′
call_cicsenv=1
user_work=′ C:\worktmp′
cobol_type=′ IBM′
The modified ELAENV.CMD file identifies the drive and directory where VisualAge
Generator Workgroup Services, CICS OS/2, and VisualAge COBOL are installed.
We used P-WARP as our operating system with an active code page of 1381 and
support enabled for the 437 code page. The ELAENV.CMD file also identifies the NLS
choice of Simplified Chinese (CHS).
See 3.2.1, “CICS OS/2 Server” on page 29 for additional information on configuring
VisualAge Generator Workgroup Services for CICS OS/2.
C:\EZERDEV2\EFK2MBDB.TPL
Not all users have authority to create plans for accessing the database on the
mainframe. You can change the DB-access plan directly into the template file. During
configuration, we use the existing plan for the mainframe. Also, check what kinds of
TRANSID the plan supports. You can use only one of those TRANSIDs to
communicate with the remote system.
/*************************************************************/
/* Sample Options file for MVS CICS */
/*************************************************************/
/CICSENTRIES=NONE
/DATA=31
/JOBCARD=EFK2MJOB.TPL
/NOCICSDBCS
/NOENDCOMMAREA
/NOGENRET
/PRINTDEST=EZEPRINT
/SYNCDXFR
/SYSTEM=MVSCICS
/TWAOFF=0
/WORKDB=AUX
/SESSION=C
/PROJECTID=JOAN
/SYMPARM=ELA,′ VGEN.HS.V1R1M0′
/SYMPARM=DSYS,′ DSNA′
Import the Workgroup Services CICS groups into CICS OS/2 as follows:
• Log on with user SYSAD and password SYSAD (CICS OS/2 default user ID and
password).
• Enter the CAIM transaction ID and press enter to display import panel.
• Use the VisualAge Generator Workgroup Services ELAM transaction to verify the
import operation and make sure that VisualAge Generator applications are ready
to run.
We actually needed different linkage table entries for each client/server configuration
(two- and three-tier):
No conversion
When we called a CICS OS/2 server application, no ASCII/EBCDIC
translation was performed.
Conversion
When an MVS CICS server was called, we needed to request ASCII/EBCDIC
conversion in the linkage table entry and use the conversion table
appropriate for Simplified Chinese.
The linkage table entry used for a two-tier client/server call is as follows:
To provide complete support for the 1381 code page, we changed the 44th byte in the
C:\EZERDEV2\ELACNCHS.CTB conversion table to a 1 as follows:
• One DLC Adapter Parameter definition to specify data link control characteristics
of the network adapter.
• A local logical unit definition for each LU alias specified in a TCS entry that
defines a remote CICS system to CICS OS/2.
• One or more MODE definitions to specify sets of session properties that are used
in binding APPC sessions.
• A transaction program definition for every local transaction that can be invoked in
an inbound request from a remote system.
Figure 111 on page 150 contains the MVSCICS.NDF file with APPC session support for
the server workstation connection to MVS CICS.
DEFINE_LOGICAL_LINK LINK_NAME(HOST0001)
DESCRIPTION(Connection to the USIBMNR Network)
FQ_ADJACENT_CP_NAME(USIBMNR.NRMCMC1 )
ADJACENT_NODE_TYPE(LEN)
DLC_NAME(IBMTRNET)
ADAPTER_NUMBER(0)
DESTINATION_ADDRESS(X′400020600632′)
ETHERNET_FORMAT(NO)
CP_CP_SESSION_SUPPORT(NO)
SOLICIT_SSCP_SESSION(YES)
NODE_ID(X′05D00000′ )
ACTIVATE_AT_STARTUP(YES)
USE_PUNAME_AS_CPNAME(NO)
LIMITED_RESOURCE(USE_ADAPTER_DEFINITION)
LINK_STATION_ROLE(USE_ADAPTER_DEFINITION)
MAX_ACTIVATION_ATTEMPTS(USE_ADAPTER_DEFINITION)
EFFECTIVE_CAPACITY(USE_ADAPTER_DEFINITION)
COST_PER_CONNECT_TIME(USE_ADAPTER_DEFINITION)
COST_PER_BYTE(USE_ADAPTER_DEFINITION)
SECURITY(USE_ADAPTER_DEFINITION)
PROPAGATION_DELAY(USE_ADAPTER_DEFINITION)
USER_DEFINED_1(USE_ADAPTER_DEFINITION)
USER_DEFINED_2(USE_ADAPTER_DEFINITION)
USER_DEFINED_3(USE_ADAPTER_DEFINITION);
DEFINE_LOCAL_LU LU_NAME(NRMKJ00I)
DESCRIPTION(Local LU)
LU_ALIAS(NRMKJ00I)
NAU_ADDRESS(INDEPENDENT_LU);
DEFINE_PARTNER_LU FQ_PARTNER_LU_NAME(USIBMNR.NRACICS1 )
DESCRIPTION(NRACICS1 CICS on CARMVS1)
PARTNER_LU_ALIAS(NRACICS1)
PARTNER_LU_UNINTERPRETED_NAME(NRACICS1)
MAX_MC_LL_SEND_SIZE(32767)
CONV_SECURITY_VERIFICATION(NO)
PARALLEL_SESSION_SUPPORT(YES);
Figure 111 (Part 1 of 3). CM/2 NDF File for Server Workstation Host Connection
DEFINE_PARTNER_LU_LOCATION FQ_PARTNER_LU_NAME(USIBMNR.NRACICS1 )
DESCRIPTION(NRACICS1 CICS on CARMVS1)
WILDCARD_ENTRY(NO)
FQ_OWNING_CP_NAME(USIBMNR.NRMCMC1 )
LOCAL_NODE_NN_SERVER(NO);
DEFINE_PARTNER_LU_LOCATION FQ_PARTNER_LU_NAME(USIBMNR.NRARDSNA )
WILDCARD_ENTRY(NO)
FQ_OWNING_CP_NAME(USIBMNR.NRMCMC1 )
LOCAL_NODE_NN_SERVER(NO);
DEFINE_MODE MODE_NAME(LU62APPX)
DESCRIPTION(LU62 logmode)
COS_NAME(CPSVCMG )
DEFAULT_RU_SIZE(NO)
MAX_RU_SIZE_UPPER_BOUND(1024)
RECEIVE_PACING_WINDOW(4)
MAX_NEGOTIABLE_SESSION_LIMIT(32767)
PLU_MODE_SESSION_LIMIT(8)
MIN_CONWINNERS_SOURCE(2)
COMPRESSION_NEED(PROHIBITED)
PLU_SLU_COMPRESSION(NONE)
SLU_PLU_COMPRESSION(NONE);
DEFINE_MODE MODE_NAME(IBMDB2LM)
DESCRIPTION(LU6.2 Log Mode for DB2)
COS_NAME(#CONNECT)
DEFAULT_RU_SIZE(NO)
MAX_RU_SIZE_UPPER_BOUND(4096)
RECEIVE_PACING_WINDOW(8)
MAX_NEGOTIABLE_SESSION_LIMIT(32767)
PLU_MODE_SESSION_LIMIT(4)
MIN_CONWINNERS_SOURCE(2)
COMPRESSION_NEED(PROHIBITED)
PLU_SLU_COMPRESSION(NONE)
SLU_PLU_COMPRESSION(NONE);
DEFINE_DEFAULTS IMPLICIT_INBOUND_PLU_SUPPORT(YES)
DEFAULT_MODE_NAME(BLANK)
MAX_MC_LL_SEND_SIZE(32767)
DIRECTORY_FOR_INBOUND_ATTACHES(*)
DEFAULT_TP_OPERATION(NONQUEUED_AM_STARTED)
DEFAULT_TP_PROGRAM_TYPE(BACKGROUND)
DEFAULT_TP_CONV_SECURITY_RQD(NO)
MAX_HELD_ALERTS(10);
Figure 111 (Part 2 of 3). CM/2 NDF File for Server Workstation Host Connection
DEFINE_TP TP_NAME(CVMI)
PIP_ALLOWED(NO)
FILESPEC(C:\CICS300\RUNTIME\FAACLPIN.EXE)
PARM_STRING(CVMI)
CONVERSATION_TYPE(ANY_TYPE)
CONV_SECURITY_RQD(NO)
SYNC_LEVEL(EITHER)
TP_OPERATION(NONQUEUED_AM_STARTED)
PROGRAM_TYPE(BACKGROUND)
RECEIVE_ALLOCATE_TIMEOUT(INFINITE);
DEFINE_TP TP_NAME(CRSR)
PIP_ALLOWED(NO)
FILESPEC(C:\CICS300\RUNTIME\FAACLPIN.EXE)
PARM_STRING(CRSR)
CONVERSATION_TYPE(ANY_TYPE)
CONV_SECURITY_RQD(NO)
SYNC_LEVEL(EITHER)
TP_OPERATION(NONQUEUED_AM_STARTED)
PROGRAM_TYPE(BACKGROUND)
RECEIVE_ALLOCATE_TIMEOUT(INFINITE);
DEFINE_TP TP_NAME(CRTE)
PIP_ALLOWED(NO)
FILESPEC(C:\CICS300\RUNTIME\FAACLPIN.EXE)
PARM_STRING(CRTE)
CONVERSATION_TYPE(ANY_TYPE)
CONV_SECURITY_RQD(NO)
SYNC_LEVEL(EITHER)
TP_OPERATION(NONQUEUED_AM_STARTED)
PROGRAM_TYPE(BACKGROUND)
RECEIVE_ALLOCATE_TIMEOUT(INFINITE);
DEFINE_CPIC_SIDE_INFO SYMBOLIC_DESTINATION_NAME(NRARDSNA)
DESCRIPTION(CPIC Information for DB2 DSNA subsystem)
PARTNER_LU_ALIAS(NRARDSNA )
MODE_NAME(IBMDB2LM)
SNA_SERVICE_TP_NAME(X′ 0 7 ′ , 6 DB);
START_ATTACH_MANAGER;
Figure 111 (Part 3 of 3). CM/2 NDF File for Server Workstation Host Connection. The
definitions included here provided support for a CICS OS/2 to MVS CICS connection (used to
implement server calls) and a DB2/2 to DB2 MVS DRDA connection (remote database access).
The remote database access connection was not used during the implementation of DBCS.
We have defined two APPC (LU6.2) sessions in our MVSCICS.NDF file. One is for MVS
CICS, the other is for a DRDA connection from DB2/2 on the server workstation to DB2
MVS. The mode name for the MVS CICS connection is LU62APPX, while the mode
name for the DB2 MVS connection is IBMDB2LM.
A detailed review of the CICS Client configuration is available in 3.2.3, “CICS Client”
on page 44.
We connected the CICS Client on our client workstation with CICS OS/2 on the server
workstation using TCP/IP. Figure 112 on page 153 contains an extract of part of our
CICS Client initialization file (CICSCLI.INI).
;--------------------------------------------------------------
; Driver section - This section defines a communications protocol DLL
; used to communicate with a server. There may be
; several Driver sections.
;
; The default example is for NetBIOS communications. Further examples
; for TCP/IP and SNA communications are shown but are commented out.
When we started the CICS Client program (CICSCLI), we used these commands:
The first command told the CICS Client that we wanted a session with the CHINA1
server (/S=CHINA1) and that we wanted to use a specific initialization file
(/F=CICSCLI.INI). The second command told the CICS Client that we wanted to use a
specific user ID and password (/U=sysad /P=sysad) for the CHINA1 connection
(/C=CHINA1).
The user ID sysad, the default system administrator ID for CICS OS/2, was used during
our testing.
The CICS Client initialization file shown in Figure 112 also contains support for a
direct connection to MVS CICS. If we removed the comment markers (;) from the
definitions for the CICS1 server and the SNA driver, we could connect directly to MVS
CICS from the client workstation (if the appropriate CM/2 definitions have been made).
If you have installed the English version of CICS OS/2, you need to change the TCT
entry for the V123 terminal to define a code page value of 1381 (Simplified Chinese). If
you have installed P-CICS OS/2, then 1381 is the default code page.
We used the CEDA transaction to customize CICS OS/2 to identify our system as a
unique system that supports VisualAge Generator applications (SIT changes), to define
a link to the remote MVS CICS sytem (TCS entry), and to provide support for calling a
remote program on the MVS CICS system (PPT entry).
Figure 113 contains an extract of our modified CICS OS/2 SIT entry.
System Sizes
CWA size 0
Maximum TWA size 1024
Number of trace entries 200
Task Control
System Communications
Local System ID CICI
Local System Appl id CHINA1
Default Remote System ID J00I
TCP/IP Support
TCP/IP local host name 9.37.200.70
TCP/IP local host port *
Maximum tasks in TCP/IP 10
Miscellaneous
Load PNA Support N
PNA Model Terminal MPNA
Initial Transaction ID CLOG
Dump on Abend N
Date Format MMDDYY
External File Manager Name
User Conversion Table
CICS OS/2 requires a terminal control table system entry (TCS) for any remote CICS
system with which it may communicate. Figure 114 contains the CICS OS/2 TCS entry
for our remote MVS CICS sytem.
System ID J00I
Group Name DBCSG
Connection Type APPC
Connection Priority 086
Description Communicate with MVS CICS NRARCICS1
Session Details
Session Count 12
Session Buffer Size 1024
Attach Security L
Partner Code Page 0037
APPC Details
System ID The name of the remote system with which CICS OS/2
communicates.
Session count The maximum number of concurrent sessions that can be active.
This value should match the following parameters:
Attach security L means local security, so that the user ID and password are not
passed to the remote system. It assumes that the user is
authorized.
Partner code page Page 37 is for U.S. EBCDIC used by our MVS CICS host.
Mode name Defines the session properties for the LU6.2 sessions. It matches
an entry in the CM/2 SNA features mode list.
LU alias The alias of the local LU defined with CM/2. It is used by CICS
OS/2 instead of the actual local LU name.
Partner LU alias The name is used by CICS OS/2 instead of the fully qualified
partner LU name to refer to the remote CICS system. CICS OS/2
uses this name to obtain the SNA network name of the remote
system. All intersystem communications take place between the
local LU specified by the LU alias, and the Partner LU specified by
this Partner LU alias. This name must match the alias in the CM/2
partner LU definition.
Programs and map sets to be used in CICS OS/2 do not necessarily need an entry in
the processing program table (PPT). If a program is called for which no PPT entry
exists, CICS OS/2 will try to locate an executable version of the program. If an
executable version of the program is found, it is loaded as if there had been a PPT
entry.
When we configure the DBCS sample application to call a VisualAge Generator server
application in CICS, then OS/2 does not need a PPT entry. We could have defined a
PPT, but no remote system is assigned.
Program(P)/Map(M)/Data(D) P
Resident(P,T,N)/Remote(R) R
Remote (R) SYSID Demands the name of a valid TCS entry defined to CICS OS/2.
We used the default transaction CPMI, so we did not define any PCT entries in MVS
CICS.
• Connection
• Session
• Transaction
• Program
Note: The authority to create and modify MVS CICS resource definitions may be
restricted, so you may have to ask the CICS system administrator for assistance.
The connection and session resources are used to communicate with CICS OS/2. The
transaction and program resources are used to support the remote call of a VisualAge
Generator server application from CICS OS/2.
Figure 116 on page 158 contains the MVS CICS connection definition for the remote
CICS OS/2 system.
SYSID=CICS APPLID=NRACICS1
Figure 116. MVS CICS Connection Definition for CICS OS/2 System
Figure 117 on page 159 contains the MVS CICS session definition for the remote CICS
OS/2 system.
SYSID=CICS APPLID=NRACICS1
Figure 117. MVS CICS Session Definition for CICS OS/2 System
Connection Defines the name of the connection associated with this session.
It must match the
Mode Name The log mode entry name. It must match the MODEENT name in
the VTAM MODETAB.
• Session count in the CICS OS/2 TCS entry for the remote CICS
system
• Mode session limit in the CM/2 SNA features mode definition
SEND SIZE The RU size for sending data. This value should match the:
RECEIVE SIZE The RU size for receiving data. This value should match all of
these:
We used the default CICS mirror transaction CPMI in our configuration. This definition
needed to be modified to increase the TWA size as required by VisualAge Generator
applications. Figure 118 on page 161 contains the modified MVS CICS transaction
definition for the CPMI mirror transaction.
SYSID=CICS APPLID=NRACICS1
Figure 119 on page 162 contains the MVS CICS program definition for the VisualAge
Generator server application that was defined as remote on the CICS OS/2 system
(see Figure 115 on page 157).
SYSID=CICS APPLID=NRACICS1
• Distributed function: GUI client or local server calls a remote server. This is
implemented in the VGPING sample application.
This approach required the use of multiple workstations and a choice between
CICS-based or DCE-based client/server communications options. 19
Multiple database access included support for distributed unit of work management as
implemented using the VisualAge Generator EZECONCT statement
A.1.1 Objectives
The objective of the VGPING sample application was to make our job of building and
testing different client/server communication configurations easier. To do this, we
built a custom VisualAge Generator client/server application that satisfies these
functional objectives:
19 Although the IMS APPC, VisualAge Generator middleware, CA/400, and MQI approaches to client/server were
discussed in this publication, we did not implement those scenarios.
• ITF
• OS/2
• Windows 3.11 (Not implemented)
• Windows 95
• Windows NT
These client/server communication options and target environments are supported for
calls to tier-2 servers from the client or tier-3 servers from tier-2 servers:
• ITF (no client/server communication required)
− CICS OS/2
− CICS NT
− CICS/6000
− MVS CICS*
− VSE CICS (Not implemented)
− OS/2
− Windows NT
− AIX
− MVS CICS (Not implemented)
− MVS IMS (Not implemented)
For example, the VGPING sample application could support two-tier call scenarios
such as:
The VGPING sample application could also support three-tier call scenarios, such as:
• ITF GUI client calls a CICS OS/2 server which calls a CICS/6000 server
(CICS-based client/server communication).
• Windows 95 GUI client calls a Windows NT server which calls an AIX server
(DCE-based client/server communication).
• OS/2 GUI client calls an OS/2 server (DCE-based client/server communication)
which calls a CICS/6000 server (CICS-based client/server communication).
Not all the potential call scenarios are possible or make sense in a production
environment. This VGPING sample application capability made the task of
implementing and testing multiple client/server configurations easier to perform. You
can use the VGPING sample application as a simple but effective testing tool for your
preferred client/server communication configurations.
Not all the possible scenarios have been implemented and tested. We believe that by
including support for these configurations in the sample application we can help you
define and test your desired client/server communication configuration.
A.1.3 Function
The VGPING sample application provides the following functions:
• Optional selection of a tier-3 server target (tier-2 server calls local or remote
server)
The server name determines the position in the two- or three-tier call path and
target runtime platform. The server names are shown in Table 8.
Ping Call servers without any SQL processing. Tests only the client/server
communication configuration.
Table 8. Sample application Servers. The full ser ver name and the name used in the VGPING client user
interface are shown. The name in parentheses is the name used in the VGPING client selection lists. We
defined, but did not implement, all the client/server configurations listed.
Client/Server Communication Two-Tier Server (Name in sample Three-Tier Server (Name in
Option application list box) sample application list box)
ITF Only VGL2ITF (L2ITF) VGL3ITF (L3ITF)
Local Calls VGL2OS2 (L2OS2) VGL2WNT (L2WNT)
VGC2AIX (C2AIX) VGC3AIX (C3AIX)
VGC2MVS (C2MVS) VGC3MVS (C3MVS)
CICS VGC2OS2 (C2OS2) VGC3OS2 (C3OS2)
VGC2VSE (C2VSE) VGC3VSE (C3VSE)
VGC2WNT (C2WNT) VGC3WNT (C3WNT)
VGD2AIX (D2AIX) VGD3AIX (D3AIX)
VGD2IMS (D2IMS) VGD3IMS (D3IMS)
DCE VGD2MVS (D2MVS) VGD3MVS (D3MVS)
VGD2OS2 (D2OS2) VGD3OS2 (D3OS2)
VGD2WNT (D2WNT) VGD3WNT (D3WNT)
VisualAge Generator Middleware
VGA2400 (A2400) VGS3400 (S3400)
for CA/400
VisualAge Generator Middleware
VGS2IMS (S2IMS) VGS3IMS (S3IMS)
for IMS/VS
VisualAge Generator Middleware
VGT2400 (T2400) VGT3400 (T3400)
using TCP/IP
VisualAge Generator Middleware
VGP2OS2 (P2OS2) VGP3OS2 (P3OS2)
using Named Pipes
VisualAge Generator Middleware
VGS2OS2 (S2OS2) VGS3OS2 (S3OS2)
using LU62
EZERT8 Any error code information generated by a call from a GUI to the
two-tier server and a call from a two-tier server to a three-tier server
EZEUSRID
User ID value as seen by the two-tier and three-tier servers.
Figure 120 shows the primary window of the VGPING GUI client application.
• Display SQL data retrieved by each server for both two- and three-tier
configurations. Data for the tier-2 server is displayed on the primary window. All
SQL data retrieved by both the tier-2 and tier-3 servers can be displayed by
clicking on the Inquired Server Data push button to open the server data window
(see Figure 121 on page 167).
There are many uniquely named server applications, representing most of the
available two- and three-tier client/server configurations supported by VisualAge
Generator. Each server application for a given tier has the same main process.
Figure 122 shows the structure diagram of one of the tier-2 servers.
The tier-3 server structure is similar, but does not support calling additional server
applications.
Linkage table
The linkage table files used during generation and runtime processing are
provided on the diskette.
A.2.1 Objectives
The objective of the DUOW sample application was to make our job of building and
testing different remote and distributed database access configurations easier. To do
this, we built a custom VisualAge Generator application that satisfies these functional
objectives:
• Captures VisualAge Generator provided return codes for server SQL requests.
A.2.2 Overview
Our DUOW sample application can access a table in one or two different databases.
We use the EZECONCT statement to implement single database access using a
remote database access connection and multiple database access using the available
DUOW features.
The table name used in each database is the same: STAFF. The creator ID for the
table is based on:
• The user ID used during SQL bind processing for remote database access
• The user ID used during EZECONCT processing for distributed database access
Because our table name is the same in each database we connect to, we can bind the
VisualAge Generator application to each target database without problems.
A.2.3 Function
The DUOW sample application provides the following functions:
SQL requests will either be issued against the STAFF table in a single database
using remote database access or against the STAFF table in two databases using
DUOW support. The notebook page active at the time of the request determines
which database will be used: one or both.
Response time In seconds, the time elapsed between issuance of a call by the
GUI client and the return from database logic server
The actual database connection and access processing is implemented in the called
application DUOWAPP. Figure 124 shows the structure diagram and the main process
of the DUOWAPP application.
Sample database
Each server application accesses an SQL table named STAFF. The STAFF
table was implemented in the DB2 environment used in each target runtime
environment.
The STAFF table is found in the sample database provided as part of most
DB2 database installations. An IXF file for this table is provided on the
diskette.
Linkage table
The linkage table files used during generation and runtime processing are
provided on the diskette.
References in this publication to IBM products, programs or services do not imply that
IBM intends to make these available in all countries in which IBM operates. Any
reference to an IBM product, program, or service is not intended to state or imply that
only IBM′s product, program, or service may be used. Any functionally equivalent
program that does not infringe any of IBM′s intellectual property rights may be used
instead of the IBM product, program or service.
Information in this book was developed in conjunction with use of the equipment
specified, and is limited in application to those specific hardware and software
products and levels.
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 the IBM Director of Licensing,
IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594 USA.
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 Corporation, Dept. 600A, Mail Drop
1329, Somers, NY 10589 USA.
The information contained in this document has not been submitted to any formal IBM
test and is distributed AS IS. The use of this information or the implementation of any
of these techniques is a customer responsibility and depends on the customer′s ability
to evaluate and integrate them into the customer′s operational environment. While
each item may have been reviewed by IBM for accuracy in a specific situation, there
is no guarantee that the same or similar results will be obtained elsewhere.
Customers attempting to adapt these techniques to their own environments do so at
their own risk.
This information was current at the time of publication, but is continually subject to change.
The latest information may be found at URL http://www.redbooks.ibm.com.
• Tools disks
To get LIST3820s of redbooks, type one of the following commands:
TOOLCAT REDBOOKS
http://w3.itso.ibm.com/redbooks
http://www.elink.ibmlink.ibm.com/pbl/pbl
• Internet Listserver
With an Internet e-mail address, anyone can subscribe to an IBM Announcement
Listserver. To initiate the service, send an e-mail note to
announce@webster.ibmlink.ibm.com with the keyword subscribe in the body of the note (leave
the subject line blank). A category form and detailed instructions will be sent to you.
• Online Orders (Do not send credit card information over the Internet) — send orders to:
IBMMAIL Internet
In United States: usib6fpl at ibmmail usib6fpl@ibmmail.com
In Canada: caibmbkz at ibmmail lmannix@vnet.ibm.com
Outside North America: dkibmbsh at ibmmail bookshop@dk.ibm.com
• Telephone orders
• Internet Listserver
With an Internet e-mail address, anyone can subscribe to an IBM Announcement
Listserver. To initiate the service, send an e-mail note to
announce@webster.ibmlink.ibm.com with the keyword subscribe in the body of the note
(leave the subject line blank).
Company
Address
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.
Index 185
DCE-based client/server (continued) DCE-based client/server communication
dcecp (continued) introduction 9
directories 61, 65 Open Blueprint assessment 12
groups 60 DCE.CNF 77
organizations 60 dcecp
server principal authority 62 adding principal to group 62
target directory 65 directories 61, 65
users 60 groups 60
dcesecure 88 organizations 60
GUI client workstation server principal authority 62
OS/2 configuration 68 target directory 65
Windows 95 configuration 73 users 60
installation DFHMIR 38
AIX 59 distributed data 103
management 60 distributed function 103
processing flow 55 distributed presentation 103
rgy_edit 77 DPATH
key table 77 linkage table 20
running applications DRDA 8
DCE server program configuration 75 connectivity 104
DCE.CNF configuration file 77 DUOW
overview 75 EZECONECT 111
starting DCE server program 77, 78 implementation 111
trace log 81 multiple database connection 114
using the sample application 80 testing with ITF 115
scenarios 56 transaction manager database 113
security
authorization required 88
dcesecure 88
E
forcing logon 89
ELAENV.CMD 33
implementation 88
ELARTRDB_tttt 22
implementing authorization checking 93
ELARUNC.CMD 33
logon required 88 environment variables
unauthenticated 88 CICS/6000 41
using dcesecure 93 CSOLINKTBL 78, 145
server principal authority 62 CSOTIMEOUT 145
servers 56 CSOTROPT 48, 78, 145
slim client 68 CSOTROUT 145
target directory 65 CSOUEXIT 22, 23, 145
TCP/IP 58 DB2DBDFT 22, 108
terminology DB2INSTANCE 41
application server workstation 57 DBCS-enabled client/server 145
CDS client 57 ELARTRDB_tttt 22, 36, 108
DCE cell 57 EZERNLS 41
DCE client 57 EZERSQLDB 22, 36, 41, 78, 108
DCE server program 57 FCWDB2DIR 41
GUI client workstation 57 FCWDBNAME_appl 22, 108
VisualAge Generator server application 57 FCWDBPASSWORD 41
unauthenticated 64 FCWDBUSER 41
user definitions FCWDPATH 41
client 59 FCWLIBPATH 41
CSODCES 59 FCWTROPT 78, 109
dcecp 60 LIBPATH 41
group 59 SQLDBDFT 108
implementation 60 working with 108
organization 59 errors
principals 59 CAIM import failure 35
REMOTECOMTYPE=dcesecure 59 CSO7800E 100
server 59
N
NetBIOS 31
I network-wide directory 7
IBM COBOL network-wide security 7
CICS configuration 34 NLS 140
DBCS-enabled client/server 145
integration
global transparent access 7
network-wide directory 7 O
network-wide security 7 objectives 2
single sign-on 7 Open Blueprint
introduction assessment 9, 12, 13, 16
client/server configuration options 2 CICS-based client/server communication 9
communication services 3 DCE-based client/server communication 12
integration objectives 7 summary 16
objectives 2 VisualAge Generator middleware client/server
Open Blueprint 3 communication 13
Index 187
Open Blueprint (continued) S
communication services 3 sample application
components 4 DBCS-enabled client/server 143
application-enabling services 4 description 163
Application/Workgroup services 4 DUOW configurations 116
applications and development tools 4 generation
common transport semantics 5 CICS OS/2 servers 37, 38
communication services 5 CICS/6000 servers 41, 43
data access services 5 DCE OS/2 client 69
distributed-systems services 5 DCE OS/2 servers 67
distribution services 5 DCE Windows 95 client 74
local operating system services 5 DCE Windows NT servers 72
network services 5 GUI client for CICS servers 45
presentation services 4 introduction 163
signalling and control plane 5 linkage table
subnetworking 5 CICS OS/2 servers 37
systems management 5 DCE OS/2 client 69
critical services DCE OS/2 servers 67
application/workgroup services 5 DCE Windows 95 client 74
distribution services 6 DCE Windows NT servers 71
naming and directory 6 GUI client generation for CICS 46
security 6 GUI client runtime for CICS 48
time 6 preparation
transaction manager 7 CICS OS/2 servers 37
transaction monitor 5 CICS/6000 servers 41
introduction 3 running
positioning VisualAge Generator 3 DCE trace log 81
DCE-based client/server 80
VGPING
P description 163, 168
PING 58 function 165, 169
principals 59 introduction 163, 168
project scope 2 objectives 163, 168
protocols 8 overview 164, 168
choices 26, 54 program materials 167, 171
CICS OS/2 31 user interface 166, 169
CICS-based client/server 26 security
DCE-based client/server 54 CICS OS/2 31
NetBIOS 31 DCE-based client/server
TCP/IP 31, 40 authorization required 88
forcing logon 89
implementation 88
implementing authorization checking 93
R
logon required 88
READIBM.EXE 140
using dcesecure 93
remote data 103
dcesecure 88
remote presentation 103
SNT 31
remote procedure call
unauthenticated 88
implementation options 9
UPM 31
introduction 8
service name 118
REXEC 42
single sign-on 7
rgy_edit 77
SNT 31
runtime
SQL COMMIT WORK 10
CSOUEXIT 23
SQL ROLLBACK 10
database authorization 23
system initialization table
database identification 22
CICS OS/2 30, 32, 36, 154
environment variables 22
DBCS implementation 154
UPM 23
examples 32
T W
TCP/IP Workgroup Services
CICS OS/2 31 CAIM transaction 34
CICS/6000 40 CICS configuration 33, 34, 36
DB2 configuration 117 CICS/6000 41
DBCS client/server communication 141 CICS/6000 installation 39
DCE 58 ELAENV.CMD 33
PING 58 ELAEX300.BTR 34
service name 118 ELAM transaction 36
testing ELARUNC.CMD 33
:CALLLINK 19 FAAAEFIE.BTR 34
bind 126, 131, 133 transaction work area 36
calling generated applications 19
CSOLINKTBL 20
CSOUEXIT 22
current ID 116
database authorization 21, 22
database identification 21
DUOW access
bind 126, 131, 133
generation 126
preparation 126
with local and remote databases 131
with local databases 127
with remote databases 133
DUOW with ITF 115
external calls 20
EZECONCT 115
ITF 19
linkage table 19, 20
remote calls 20
UPM 22
U
UPM
CICS OS/2 31
database authorization 22, 23
V
VisualAge COBOL
CICS configuration 34
DBCS-enabled client/server 145
VisualAge Generator
database
identification 108
VisualAge Generator middleware client/server
communication
implementation issues 16
introduction 9
Open Blueprint assessment 13
Index 189
190 VisualAge Generator Client/Server Communications
ITSO Redbook Evaluation
VisualAge Generator Client/Server Communications Examining the Options
SG24-4237-00
Your feedback is very important to help us maintain the quality of ITSO redbooks. Please
complete this questionnaire and return it using one of the following methods:
• Use the online evaluation form found at http://www.redbooks.com
• Fax this form to: USA International Access Code + 1 914 432 8264
• Send your comments in an Internet note to redeval@vnet.ibm.com
Please rate your overall satisfaction with this book using the scale:
(1 = very good, 2 = good, 3 = average, 4 = poor, 5 = very poor)
Was this redbook published in time for your needs? Yes____ No____
If no, please explain:
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
_____________________________________________________________________________________________________
Printed in U.S.A.
SG24-4237-00