Rocket U2 Clients and APIs Administrative Supplement for Current and Legacy Client APIs

49 Pages·2015·1.1 MB·English

by  Rocket Software

Rocket U2 Clients and APIs
Administrative Supplement for Current and
Legacy Client APIs
September 2015
September 2015
UCC-S2015-SUPP-UG-01
Notices
Edition
Publication date: September 2015
Book number: UCC-S2015-SUPP-UG-01
Product version: September 2015
Copyright
© Rocket Software, Inc. or its affiliates 1988-2015. All Rights Reserved.
Trademarks
Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks go
to: www.rocketsoftware.com/about/legal. All other products or services mentioned in this document
may be covered by the trademarks, service marks, or product names of their respective owners.
Examples
This information might contain examples of data and reports. The examples include the names of
individuals, companies, brands, and products. All of these names are fictitious and any similarity to
the names and addresses used by an actual business enterprise is entirely coincidental.
License agreement
This software and the associated documentation are proprietary and confidential to Rocket Software,
Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance with
the terms of such license.
Note: This product may contain encryption technology. Many countries prohibit or restrict the
use, import, or export of encryption technologies, and current use, import, and export regulations
should be followed when exporting this product.
2
Corporate information
Rocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,
and compliance; database servers and tools; business information and analytics; and application
development, integration, and modernization.
Website: www.rocketsoftware.com
Rocket Global Headquarters
th
77 4 Avenue, Suite 100
Waltham, MA 02451-1468
USA
To contact Rocket Software by telephone for any reason, including obtaining pre-sales information
and technical support, use one of the following telephone numbers.
Country Toll-free telephone number
United States 1-855-577-4323
Australia 1-800-823-405
Belgium 0800-266-65
Canada 1-855-577-4323
China 800-720-1170
France 0800-180-0882
Germany 08-05-08-05-62
Italy 800-878-295
Japan 0800-170-5464
Netherlands 0-800-022-2961
New Zealand 0800-003210
South Africa 0-800-980-818
United Kingdom 0800-520-0439
Contacting Technical Support
The Rocket Customer Portal is the primary method of obtaining support. If you have current
support and maintenance agreements with Rocket Software, you can access the Rocket Customer
Portal and report a problem, download an update, or find answers to in the U2 Knowledgebase.
To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go to
www.rocketsoftware.com/support.
In addition to using the Rocket Customer Portal to obtain support, you can send an email to
[email protected] or use one of the following telephone numbers.
Country Telephone number
North America [phone]
United Kingdom/France [phone] or [phone]
Europe/Africa [phone]
Australia [phone] or [phone]
New Zealand +0800 505 515
3
Contents
Notices...................................................................................................................................................................................2
Corporate information.........................................................................................................................................................3
Chapter 1: Introduction........................................................................................................................................................6
UCI..............................................................................................................................................................................6
UniOLEDB..................................................................................................................................................................6
InterCall.....................................................................................................................................................................6
UniObjects.................................................................................................................................................................6
UniObjects for Java..................................................................................................................................................7
UniObjects for .NET...................................................................................................................................................7
JDBC Driver for UniVerse and UniData...................................................................................................................7
Chapter 2: Maintaining the UniRPC.....................................................................................................................................8
System requirements...............................................................................................................................................8
How the UniRPC works............................................................................................................................................8
Maintaining the UniRPC...........................................................................................................................................8
UniRPC maintenance on UniVerse systems................................................................................................9
Defining the UniRPC port number (UniVerse Only)........................................................................9
Maintaining the hosts file (UniVerse Only)....................................................................................10
Adding a node.................................................................................................................................10
Modifying a node............................................................................................................................10
Removing a node............................................................................................................................10
Starting the UniRPC on Windows platforms.................................................................................10
From the Control Panel..................................................................................................................11
From the UniVerse Control Panel..................................................................................................11
At the MS-DOS prompt...................................................................................................................11
Stopping the UniRPC on Windows platforms...............................................................................11
From the Control Panel..................................................................................................................11
From the UniVerse Control Panel..................................................................................................12
At the MS-DOS prompt...................................................................................................................12
Starting the UniRPC daemon on UNIX systems............................................................................12
Stopping the UniRPC daemon on UNIX systems..........................................................................12
UniRPC maintenance on UniVerse servers...............................................................................................12
About the unirpcservices file.................................................................................................................................13
UniVerse systems........................................................................................................................................13
UniData systems.........................................................................................................................................14
Chapter 3: The UCI Configuration Editor..........................................................................................................................15
UCI configuration file..............................................................................................................................................15
System requirements.............................................................................................................................................15
Starting the UCI Configuration Editor...................................................................................................................16
Creating the UciCfgFile key in the registry...........................................................................................................16
Adding a data source.............................................................................................................................................17
Adding a parameter................................................................................................................................................18
Data source parameters.........................................................................................................................................19
Modifying a data source.........................................................................................................................................22
Deleting a data source...........................................................................................................................................23
Creating a UCI configuration file...........................................................................................................................23
Opening an alternative UCI configuration file......................................................................................................23
Reverting to the default uci.config file.....................................................................................................23
Securing configuration files...................................................................................................................................23
Modifying a configuration file and making comments........................................................................................24
New data source parameters and comments..........................................................................................24
4
Contents
Chapter 4: Accessing UniVerse Accounts..........................................................................................................................25
Running concurrent UniVerse versions.................................................................................................................25
Running UCI, UniVerse ODBC, or UniOLEDB concurrently.......................................................................25
Running InterCall, UniObjects, or UniObjects for Java concurrently......................................................26
Tracing events.........................................................................................................................................................26
Chapter 5: Device licensing................................................................................................................................................27
Licensing modes.....................................................................................................................................................27
Session licensing.........................................................................................................................................27
Device licensing..........................................................................................................................................27
Why do I need device licensing?............................................................................................................................27
Device licensing requirements...................................................................................................................28
Connection types....................................................................................................................................................28
Direct connections......................................................................................................................................28
Two-tier connections..................................................................................................................................28
Multiple-tier connections...........................................................................................................................28
Using device subkeys.................................................................................................................................29
Chapter 6: The U2 SSL Configuration Editor....................................................................................................................30
About SSL property lists.........................................................................................................................................30
List encryption........................................................................................................................................................30
Working with SSL property lists............................................................................................................................31
Loading and decrypting an SSL property list.......................................................................................................31
SSL properties.........................................................................................................................................................31
SSLVersion={SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2}.......................................................................................31
CertificateStoreType={U2 | Windows}.......................................................................................................31
CACertificate=<cert-path>[;<cert-path>...]................................................................................................32
MyCertificate=<cert-path>..........................................................................................................................32
MyPrivateKey=<key-path>..........................................................................................................................33
PrivateKeyPassword=<pass-phrase>.........................................................................................................33
CRL=<cert-path>.........................................................................................................................................33
AuthenticationDepth=<level>....................................................................................................................34
CipherSuite=<cipher-suite-string>.............................................................................................................34
TrustedPeerName=<trusted-peer-name-string........................................................................................34
AuthenticationStrength=[STRICT | GENEROUS].......................................................................................34
CertificatePath=[DEFAULT | RELATIVE | PATH=<path> | ENV=<env-var>]................................................35
ClientAuthentication=[TRUE | FALSE]........................................................................................................35
RandomFileLocation=<directory-path>....................................................................................................36
Starting the SSL Configuration Editor...................................................................................................................36
Creating an SSL property list.................................................................................................................................37
Specifying certificates................................................................................................................................39
Specifying authentication properties, CRLs, and cipher suites...............................................................41
Editing an existing SSL property list.....................................................................................................................42
Deleting an SSL property list.................................................................................................................................47
Copying an SSL property list.................................................................................................................................47
Renaming an SSL property list..............................................................................................................................48
Using the Trace feature..........................................................................................................................................48
5
Chapter 1: Introduction
U2 provides seven common APIs for writing client application programs that connect to UniVerse and
UniVerse databases.
We call them common APIs because programs written in them can access data in both databases.
The seven Client APIs are:
▪ UCI, on page 6
▪ UniOLEDB, on page 6
▪ InterCall, on page 6
▪ UniObjects, on page 6
▪ UniObjects for Java, on page 7
▪ UniObjects for .NET, on page 7
▪ JDBC Driver for UniVerse and UniData, on page 7
UCI
UCI is a C-language API. It lets developers write UNIX and Windows client programs that use SQL
statements to access and manipulate data in UniVerse and UniVerse databases. UCI is modelled on
the ODBC standard as defined in the Microsoft ODBC 2.0 specification.
It models only the API side of the ODBC standard, not the driver/transport side. Unlike the standard
ODBC interface, UCI is more closely integrated with the extended relational database model used by
UniVerse and UniVerse, with their nested tables, transaction processing support, and so forth.
UniOLEDB
UniOLEDB is U2’s OLE DB provider for UniVerse and UniVerse.
It uses Microsoft’s Universal Data Access (UDA) technology to provide applications in an enterprise
network with direct access to UniVerse and UniVerse databases.
InterCall
InterCall is an open API that lets client application programs developed on UNIX or Windows systems
access data on UniVerse or UniVerse servers.
On UNIX systems, developers can write client programs using any tool that accesses static libraries,
typically a C compiler. On Windows platforms, developers can write client programs using any tool
that accesses DLLs, for example, Visual Basic, C, or Visual C/C++.
Note: InterCall replaces and supersedes ICI (Integrated Calling Interface).
UniObjects
UniObjects is an API to UniVerse or UniVerse from Visual Basic, or from any other program
development environment that uses the Microsoft ActiveX interface.
6
UniObjects for Java
It is fully integrated with the Microsoft environment.
UniObjects for Java
UniObjects for Java is an API that lets developers create Java-based applications that access UniVerse
and UniVerse databases.
UniObjects for Java, based on the UniObjects model, is a 100% Pure Java Class Library whose objects
can take full advantage of any Java-based IDE (Integrated Development Environment).
UniObjects for .NET
UniObjects for .NET is an API that lets developers create .NET-based applications that access UniVerse
and UniVerse databases.
UniObjects for .NET is fully integrated with the Microsoft environment. 
JDBC Driver for UniVerse and UniData
The JDBC driver for UniVerse and UniData is an interface to UniVerse and UniData databases from
JDBC applications.
This book is for experienced programmers and application developers who are familiar with UniVerse
and UniData, Java, JDBC, and who want to write JDBC applications that access these databases.
Note: The JDBC Driver for UniVerse and UniData does not require any configuration for UCI and
will not need an entry within the UCI configuration file.
7
Chapter 2: Maintaining the UniRPC
The UniRPC lets local UniVerse and UniVerse systems communicate with remote systems. The
communicating systems must use TCP/IP networking software to make connections.
In this chapter the terms local and remote refer to client and server programs or systems. However,
because client programs can connect to server programs running on the same computer, remote does
not necessarily imply that the server is on another physical computer system.
This chapter describes:
▪ The UniRPC daemon (on UNIX servers)
▪ The UniRPC service (on Windows servers)
▪ The contents of the file
unirpcservices
The UniRPC on UniVerse servers requires little maintenance, other than starting and stopping the
UniRPC daemon or service. On UniVerse servers, you can also do the following:
▪ Change the port number
▪ Add entries to a UNIX file
hosts
System requirements
Before installing layered or third-party products that use the UniRPC, such as the UniDK, UniOLEDB,
the JDBC Driver for UniVerse and UniVerse, or UniAdmin, you must install and configure TCP/IP using
the instructions supplied by the TCP/IP facility vendor.
On UniVerse systems, you should then identify the systems to be networked with the database by
defining them in the /etc/hosts file. See Maintaining the hosts file (UniVerse Only), on page 10 for
more information.
How the UniRPC works
The UniRPC daemon unirpcd (or the UniRPC service unirpc) waits for a request from a client system to
connect to a server process.
When it receives a connection request, it checks the  files to verify that the client
unirpcservices
system is allowed to request a particular service. If it can, the UniRPC starts the requested service,
then returns to the listening state. Each client process connects to its own server process. Each server
process uses the same amount of system resources as a local database user.
Maintaining the UniRPC
This section describes the following:
▪ How to change the UniRPC port number (UniVerse only)
▪ How to maintain a UNIX server’s file (UniVerse only)
hosts
▪ How to start and stop the UniRPC daemon (unirpcd)
8
UniRPC maintenance on UniVerse systems
UniRPC maintenance on UniVerse systems
Use UniAdmin to:
▪ Define the UniRPC port number
▪ Maintain the hosts file on a UNIX server
Choose Network Services from the UniAdmin menu. The Network Services window appears, as
shown in the following example:
 This window has the following components:
▪ Port # field. The current port number for the UniRPC daemon.
▪ Hosts list. Displays the machine name and IP address for each node in the file.
/etc/hosts
Note: If you are using the Network Information Services (NIS, also known as Yellow Pages), you
do not need to use the /etc/hosts file to define, change, and delete network nodes. See the UNIX
networking documentation provided with your system for more information.
Defining the UniRPC port number (UniVerse Only)
Before you can use the UniRPC, you must specify the number of the port that the UniRPC is to use. You
specify the port number on the client and the server systems. If you specify a port number other than
the default, it must be the same on all systems that communicate via the UniRPC.
The current UniRPC daemon port number is displayed in the Port # field in the Network Services
window. To change the number, do the following:
1. Click Change.
The Change Port Number dialog box appears.
2. Enter a new number in the Enter new Port number field.
3. Click OK.
The new port number is saved and the Network Services window is updated with the new setting.
9
Chapter 2: Maintaining the UniRPC
To use the new port number, you must restart the UniRPC daemon (see Starting the UniRPC daemon
on UNIX systems, on page 12)
Maintaining the hosts file (UniVerse Only)
Use the Network Services option of UniAdmin to add, modify, and remove nodes in the hosts file.
These tasks are performed from the Network Services window.
Adding a node
To add a new node to the hosts file:
1. Click Add on the Network Services window.
The Add Node dialog box appears.
2. Enter the node name in the Machine Name field.
3. Enter the node address in the IP Address field.
4. Click OK.
The new node’s machine name and IP address are checked against existing entries in the
 file. If the new node matches an existing entry, a message box appears. You must
hosts
acknowledge the message before you can enter alternative values. If the new node details are
unique, the new node definition is added to the  file and the Network Services window is
hosts
updated.
Modifying a node
To modify the name or IP address of an existing entry in the hosts file:
1. Choose the node to modify by doing one of the following:
▪ Double-click the node in the Hosts list.
▪ Choose the node and click Modify.
The Modify Node dialog box appears.
2. Edit the entries in the Machine Name and IP Address fields.
3. Click OK.
The node’s machine name and IP address are checked against existing entries in the  file.
hosts
If the node details match an existing entry, a message box appears. You must acknowledge
the message before you can enter alternative values. If the node details are unique, the node
definition is added to the  file and the Network Services window is updated.
hosts
Removing a node
To remove a node definition from the hosts file:
1. Select the node from the Hosts list.
2. Click Remove.
A message box appears.
3. Click Yes. The node definition is removed from the hosts file and the Network Services window
is updated.
Starting the UniRPC on Windows platforms
On UniVerse systems you cannot use UniAdmin to start the UniRPC daemon because it uses the
UniRPC daemon to connect to the UniVerse server. On Windows platforms,  you can start the UniRPC
daemon or service in one of three ways:
10