Rocket U2 Clients and APIs

UCI Configuration Editor

Version 4.251.0

October 2016UCC-S2016-UCI-UG-01

2

NoticesEdition

Publication date: October 2016Book number: UCC-S2016-UCI-UG-01Product version: Version 4.251.0

Copyright© Rocket Software, Inc. or its affiliates 1988-2016. All Rights Reserved.

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay 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 ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe 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 withthe terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.

3

Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.

Website: www.rocketsoftware.com

Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA

To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.

Country Toll-free telephone number

United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 800-720-1170France 08-05-08-05-62Germany 0800-180-0882Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Customer Portal is the primary method of obtaining support. If you have current supportand maintenance agreements with Rocket Software, you can access the Rocket Customer Portal andreport a problem, download an update, or read answers to FAQs. To log in to the Rocket CustomerPortal 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 use one of the telephonenumbers that are listed above or send an email to support@rocketsoftware.com.

4

Contents

Notices................................................................................................................................................................................... 2

Corporate information......................................................................................................................................................... 3

Chapter 1: The UCI Configuration Editor............................................................................................................................ 5UCI configuration file................................................................................................................................................5System requirements............................................................................................................................................... 5Starting the UCI Configuration Editor.....................................................................................................................6Creating the UciCfgFile key in the registry............................................................................................................. 6Adding a data source............................................................................................................................................... 7Adding a parameter..................................................................................................................................................8Data source parameters...........................................................................................................................................9Modifying a data source.........................................................................................................................................12Deleting a data source........................................................................................................................................... 13Creating a UCI configuration file........................................................................................................................... 13Opening an alternative UCI configuration file......................................................................................................13

Reverting to the default uci.config file..................................................................................................... 13Securing configuration files................................................................................................................................... 13Modifying a configuration file and making comments........................................................................................ 14

New data source parameters and comments.......................................................................................... 14

5

Chapter 1: The UCI Configuration EditorWhen an application requests a connection to a data source, UCI uses the information in the UCIconfiguration file (uci.config or another UCI configuration file you create) to connect to the datasource.

The UCI Configuration Editor lets you:

▪ Add, modify, or delete data sources.

▪ Create your own UCI configuration file.

▪ Set up your system registry to access a particular UCI configuration file.

▪ Open a UCI configuration file different from the one that currently appears in the UCI ConfigurationEditor window.

▪ Create secure configuration files.

This tool can generate the system registry key and create a default uci.config file in the c:\U2\UniDK\config directory, if either are missing. For more details about this, refer to Creatingthe UciCfgFile key in the registry, on page 6.

Note: You must be in Administrator mode to update the registry on computers that have useraccess controls (UAC) enabled.

UCI configuration fileApplications access data sources through entries in the UCI configuration file. This file containsconnection parameters needed to route connection requests to the appropriate UniData or UniVerseserver.

When an application tries to connect to a data source, the UCI configuration file on the client machineis read to determine the name of the host system, the DBMS type, and other information.

The UCI configuration file that UCI uses is specified in the UciCfgFile key in the system registry underHKEY_LOCAL_MACHINE \SOFTWARE\Rocket Software\UniClient\UCIorHKEY_LOCAL_MACHINE\Software\Wow6432Node\Rocket Software\UniClient\UCI.

Each entry in the UCI configuration file describes the physical attributes of a connection in sufficientdetail to perform three tasks:

▪ Establish communications

▪ Start a UniData or UniVerse server process

▪ Route query and update requests

In the UCI configuration file on the client machine, you must define the UCI data sources to whichyou want applications to connect. Use the UCI Configuration Editor to define and modify data sourcedefinitions.

For more information about the UCI configuration file, see UCI Developer’s Guide.

System requirements▪ .NET Framework 4.0 Client Profile

Chapter 1: The UCI Configuration Editor

6

This UCI Editor tool is installed as part of the UniDK, 32-bit U2ODBC, 64-bit U2ODBC, and VSG clientinstallations.

It is installed in one of the following directories:

▪ C:\U2\UniDK\U2ODBC_32bit\UCI_Editor

▪ C:\U2\UniDK\U2ODBC_64bit\UCI_Editor

▪ C:\U2\UniDK\bin\UCI_Editor

Starting the UCI Configuration EditorTo start the UCI Configuration Editor on a Windows computer, from the Start menu choose Programs> Rocket U2 > UniDK > UCI Editor.

The UCI Editor window opens

The data source information in this example represents the default settings in the uci.config file,as shipped with the client product.

Note: If the uci.config file is password protected, you will be prompted for a password beforethe editor will open. If you do not know the password, you can click the Help button forinstructions on how to resolve the issue.

Creating the UciCfgFile key in the registryThe UCI configuration file that the client uses is specified in the UciCfgFile key in the system registryunder HKEY_LOCAL_MACHINE\SOFTWARE\RocketSoftware\UCI. Initially this is set touci.config, the UCI configuration file U2 ships to you.

Adding a data source

7

You must create a new UciCfgFile key if it is not already included in the registry. You may also needto create a new UciCfgFile key if the registry becomes corrupt, making the key inaccessible to yoursystem.

If the registry key does not exist, the UCI Editor will open with the UCI RegKey button visible. Click UCIRegKey to create the UciCfgFile key in the registry and to set the path to the default uci.config file. Youmust restart the UCI Configuration Editor for the changes to take effect.

Note: If the UciCfgFile exists in the registry, the UCI RegKey button will not be visible. 

Adding a data source1. Click New Data Source. The New Data Source dialog box opens, as shown in the following

example.

2. Enter a data source name.3. Under DBMSTYPE, click the type of database to which you want to connect.4. Enter the host name or the network IP address of the server to which you want to connect.

Chapter 1: The UCI Configuration Editor

8

5. Click OK to save your definition and exit the New Data Source dialog box or click Cancel to exitthe dialog box without saving your definition.The data source information now shows in the UCI Configuration Editor.

The parameters that appear automatically on the Data Source Editing section are required foreach data source you add. Their values are set according to the information you provide on theNew Data Source dialog box.

Adding a parameterAfter a data source is defined, it may become necessary to add additional parameters.

Procedure

1. Click Add Parameter. The Parameter dialog box displays.2. Click the parameter you want to add from the Parameter list. For a list of parameters, see Data

source parameters, on page 9.3. In the Value field, enter an appropriate value for the parameter. Information about the parameter

appears under Parameter Description.4. Click Set to add the parameter.5. After you finish adding parameters, click Cancel. The Data Source Adding dialog box displays all

parameters associated with the data source.

Note: To edit parameters, see “Modifying a data source” on page 3-16.

6. After you finish adding parameters for the data source, click Save Data Source.

Data source parameters

9

7. When you finish adding data sources, click Save Configuration File to save your changes.

Data source parametersEach data source definition in the UCI configuration must include the following parameters:

▪ DBMSTYPE

▪ NETWORK

▪ SERVICE

▪ HOST

Two parameters you might want to change are MAXFETCHBUFF and MAXFETCHCOLS. Use theseparameters to increase the amount of data in each buffer sent from the server to the client. This willimprove performance by reducing the number of data transfers between server and client. For moreinformation about these two parameters, see the UCI Developer’s Guide.

If the UniVerse server you are connecting to has NLS enabled, you also can add or change the NLSparameters. For information about setting the NLS parameters, see the UCI Developer’s Guide.

Warning: Adding or changing other parameters can make UCI unusable. Entries in the uci.configfile are order dependent. Changing the order will cause an error.

The following table describes the parameters that are required for each data source entry:

Parameter Description Default

DBMSTYPE Specifies the type of database you want to access(UNIDATA, UNIVERSE, or any other database type,such as DB2).

None

NETWORK Specifies the network used to access the data source(TCP/IP or LAN).

None

SERVICE Specifies the name of the server process for theDBMSTYPE you specified. For UniData, specifyudserver; for UniVerse, specify uvserver.

None

HOST Specifies the name of the server machine or itsnetwork IP address.

None

The following table describes other parameters in the Parameters list that you may want to add orchange:

Chapter 1: The UCI Configuration Editor

10

Parameter Description Default

ACCOUNT Specifies one of the following:

▪ The full path of a UniData or UniVerse accountdirectory

▪ A valid UniVerse schema name

▪ A valid UniData database name

A UniData database name is valid if it appears as anentry in the ud_database file. For UNIX systems,this file is typically located in the /usr/udxx/include path, where xx is the UniData version, suchas /usr/ud73/include. For Windows systems,it is located in the equivalent Windows path, forexample C:\U2\ud73\INCLUDE.

None

AUTOINC Produces an SQLColAttributes report if the column isan auto-increment column.

No

CASE Produces an SQLColAttributes report if the column iscase-sensitive.

Yes

DESCB4EXEC (For internal use only) Indicates if the database’sdescribe operation is legal before executing the SQLstatement.

Yes

DSPSIZE Produces an SQLColAttributes report showing thecolumn display size.

Yes

IPVERSION Specifies the IP version through which the clientwill communicate with the server. Can be one of thefollowing:

▪ IPV4

▪ IPV6

▪ IPV4_IPV6

▪ IPV6_IPV4

▪ IPVANY

IPV4

MAPERROR Maps UniVerse error codes to standard ODBCSQLSTATE error codes. Whenever the server returnsone of the mapped codes as an error condition,UCI sets the SQLSTATE variable equal to the five-character code defined in the ODBC standard.

List

MARKERNAME Indicates if the database uses names for parametermarkers. If not, the ? (question mark) is the markercharacter.

No

MAXFETCHBUFF Controls the maximum buffer size on the server tohold data rows. The server usually fills this bufferwith as many rows as possible before sending datato the client. If any single row exceeds the lengthof MAXFETCHBUFF, SQLFetch fails, and you shouldincrease the value of this parameter.

8192 bytes

Data source parameters

11

Parameter Description Default

MAXFETCHCOLS Controls the maximum number of column values theserver can put in the buffer before sending data tothe client. If the number of columns in the result setexceeds the number specified by MAXFETCHCOLS,SQLFetch fails, and you should increase the value ofthis parameter.

400 column values

NLSLCALL Specifies all components of a locale. NoneNLSLCCOLLATE Specifies the name of a locale whose sort order to

use.None

NLSLCCTYPE Specifies the name of a locale whose character typeto use.

None

NLSLCMONETARY Specifies the name of a locale whose monetaryconvention to use.

None

NLSLCNUMERIC Specifies the name of a locale whose numericconvention to use.

None

NLSLCTIME Specifies the name of a locale whose time conventionto use.

None

NLSLOCALE Specifies all components of a locale. NoneNLSMAP Specifies the name of the server’s NLS map for the

connection. For a client to connect to the serversuccessfully, the server must be able to locate thespecified map, which must also be installed in theserver’s shared memory segment.

None

NULLABLE Produces an SQLDescribeCol andSQLColAttributes report if the column is nullable.

Yes

SEARCH Produces an SQLColAttributes report if the column issearchable.

Yes

SECUREMODE Turns on/off a U2 ODBC-enabled SSL connection. NoneSSLPROPERTYLIST Specifies the SSLPROPERTY list name defined in the

SSL Configuration Editor.None

SSLPROPERTY-PASSWORD

Specifies the password defined for the SSLPROPERTYlist.

None

TXBEHAVIOR Defines default autocommit/ manual-committransaction behavior. Normally, UniVerse isautocommit by default.

1

TXCOMMIT (For internal use only) Database SQL statement forcommitting a transaction.

No

TXROLL (For internal use only) Database SQL statement forrolling back a transaction.

No

TXSTART (For internal use only) Database SQL statement forstarting a transaction.

No

TYPENAME Produces an SQLColAttributes report showing thename of the SQL TYPE for the column.

Yes

UNSIGNED Produces an SQLColAttributes report if the column isUNSIGNED.

No

UPDATE Produces an SQLColAttributes report if the column isupdatable.

Yes

USERNAME Specifies the user’s login name on the server. None

Chapter 1: The UCI Configuration Editor

12

Parameter Description Default

WALLETID Specifies the Wallet ID for Automatic DataEncryption.

None

WALLETPASS Specifies the Wallet password for Automatic DataEncryption.

None

Modifying a data source1. From the UCI Configuration Editor, click the data source you want to modify. The data source

information populates in the Data Source Editing area.You can add new parameters or edit existing ones. To add new parameters, see Adding a datasource, on page 7. To edit parameters, continue with the following steps.

2. Click the parameter you want to modify. The parameter name and current value appear underParameter Editor, as shown in the following example.

3. To remove the parameter, click Remove Parameter.4. To modify the parameter value, enter a new value in the Value field, then click Update

Parameter.5. After you finish modifying parameters for the data source, click Save Data Source.6. When you finish modifying data source information, click Save Configuration File to save your

changes.

Deleting a data source

13

Deleting a data source1. From the UCI Configuration Editor, select the data source you want to delete.2. Click the Delete Data Source button.3. When you finish deleting data sources, click Save Configuration File to save your changes.

Creating a UCI configuration fileComplete the following steps to create your own UCI configuration file.

1. From the UCI Configuration Editor, open the UCI configuration file you want to use as a base forthe new UCI configuration file. To open a file, see Opening an alternative UCI configuration file, onpage 13.

2. Choose File > Save As.3. From the Save As dialog box, navigate to the folder to which you want to save the new UCI

configuration file, specify a file name with the extension .config, then click Save.4. If there was a password set on the original configuration file, a dialog box opens and asks you to

define a password for the new configuration file. You are not required to create a password.5. Modify the new UCI configuration file with the appropriate data source information.

Opening an alternative UCI configuration file1. To open the UCI configuration file that is set in the UciCfgFile registry key, choose File > Set new

configuration file.2. To open a UCI configuration file that is different from the one set in the UciCfgFile registry key,

a. From the UCI Configuration Editor, choose File -> Open disk file.b. From the Open File dialog box, choose the appropriate UCI configuration file (the file should

have the extension .config), then click Open.

Reverting to the default uci.config file

If you have previously elected to use an alternative UCI configuration file, you can elect to use thedefault uci.config file at any time.

Click File > Use default uci.config.

Securing configuration filesThe UCI configuration files can be password-protected for an additional layer of security. When aconfiguration file is password protected, the information in the configuration file is encrypted and canthereafter only be accessed using the UCI Configuration Editor.

1. Open the UCI Configuration Editor if it is not already open.2. Make sure that the configuration file that you want to secure is the one open in the UCI

Configuration Editor. To select a new configuration file, click File > Open disk file, select theconfiguration file that you want to secure, and then click OK to return to the editor.

3. Click the Secure UCI configuration file check box.4. Click Save Config File. Click Yes when asked if you want to update the configuration file.

Chapter 1: The UCI Configuration Editor

14

This opens a new password dialog box.5. Enter the new password information, and then click OK.

Note: When the secure password is not provided correctly, the secure uci.config file will notbe opened. You can delete the secure uci.config file and the tool will create a new defaultuci.config file.

Modifying a configuration file and making commentsAfter selecting the correct UCI configuration file, you can open the configuration file to manually makeany changes.

In the UCI Configuration Editor, click Text Editor to easily access the configuration file.

New data source parameters and comments

You can define additional parameters or comments to include in the UCI configuration file.

To do either of these, click New Items in the Parameter list, then under Parameter Editor, enter oneof the following in the Parameter field:

▪ A new parameter name

New data source parameters

New parameters must begin with a C– prefix. For example, you might name a new parameter C–CATEGORY. UCI ignores any parameter beginning with the C– prefix, but UCI applications can get theparameter information using the SQLDataSources function.

Comments

To include a comment in a data source definition, open the configuration file and then enter anasterisk (*) before any comments. The comments must appear at the top of the configuration file,before the parameters in the data source definition.