DataDirect Cloud Distribution Guide

Transcription

1 DataDirect Cloud Distribution Guide August 2014

2

3 Notices For details, see the following topics: Copyright Copyright 2014 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved. These materials and all Progress software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Business Making Progress, Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, Fathom, Making Software Work Together, OpenEdge, Powered by Progress, Progress, Progress Control Tower, Progress OpenEdge, Progress RPM, Progress Software Business Making Progress, Progress Software Developers Network, Rollbase, RulesCloud, RulesWorld, SequeLink, SpeedScript, Stylus Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, AppsAlive, AppServer, BusinessEdge, Progress Easyl, DataDirect Spy, DataDirect SupportLink, Easyl, Future Proof, High Performance Integration, Modulus, OpenAccess, Pacific, ProDataSet, Progress Arcade, Progress Pacific, Progress Profiles, Progress Results, Progress RFID, Progress Responsive Process Management, Progress Software, ProVision, PSE Pro, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners. 3

4 Notices Please refer to the Release Notes applicable to the particular Progress product release for any third-party acknowledgements required to be provided in the documentation associated with the Progress product. 4

5 Table of Contents Distributing Your DataDirect Cloud Drivers...9 Branding the DataDirect Cloud Drivers...9 Managing User Accounts Using the User-Provisioning API...9 Preface...11 About this Book...11 Branding Your DataDirect Cloud Driver...11 Using This Book...12 Typographical Conventions...12 Contacting Customer Support...13 Part I: Distributing the JDBC Driver...15 Chapter 1: Branding the JDBC Driver...17 Branding the JDBC Driver in the Product Installer...17 Before Branding the JDBC Driver in the Product Installer...17 Branding the Product (JDBC)...18 Branding the JDBC Driver Using the GUI...19 Branding the JDBC Driver Using the Command-Line (UNIX/Linux)...21 Branding the JDBC Driver Using a Silent Installation...23 Creating the Response File Using the Installer (JDBC)...23 Creating a Response File Using a Text Editor (JDBC)...26 Performing the Silent Installation (JDBC)...28 Installation Log File (JDBC)...29 Branding Results (JDBC)...29 Testing the Branded JDBC Driver with DataDirect Test...29 Branding the JDBC Driver Using the Standalone Tool...30 Before Branding the JDBC Driver Using the Standalone Branding Tool...30 Branding Using the Standalone Branding Tool...30 Chapter 2: Unlocking the Branded JDBC Driver...35 Unlocking the Branded Drivers...35 Using DataDirect Test with the Branded JDBC Driver...36 Chapter 3: Distributing the Branded JDBC Driver...37 Installing the Branded JDBC Driver...37 File Distribution for the JDBC Driver

6 Files You Must Distribute...38 Optional Files...39 Files You Must Not Distribute...39 Part II: Distributing the ODBC Drivers...41 Chapter 4: Branding the ODBC Drivers...43 Branding the ODBC Drivers in the Product Installer...44 Before Branding...44 Branding the ODBC Drivers on Windows...45 Branding the ODBC Drivers Using the GUI...45 Branding the ODBC Drivers Using the Silent Installer...48 Creating a Response File for the ODBC Drivers Using the Installer...48 Creating a Response File for the ODBC Drivers Using a Text Editor...49 Performing the Silent Installation...51 The Silent Installation Log File (ODBC)...52 Branding the ODBC Driver on UNIX and Linux...52 Branding the Drivers in the GUI on UNIX and Linux...52 Branding the Drivers on UNIX and Linux Using the Command-Line Installer...55 Branding the ODBC Drivers Using the Silent Installer...57 Creating the Response File Using the GUI Installer (ODBC)...58 Creating the Response File Using the Command-Line Installer (ODBC)...58 Creating the Response File Using a Text Editor (ODBC)...59 Performing the Silent Installation...61 Branding Results...61 Branding the ODBC Drivers Using the Standalone Branding Tool...62 About the Branding Tool...62 Before You Use the Branding Tool Kit...62 Branding the Drivers on Windows...63 Branding the Drivers on UNIX and Linux...66 Chapter 5: Unlocking the ODBC Drivers...71 Understanding the Driver License Control Messages...72 Development with ODBC SDK...72 Development with Visual Basic and Other Tools...73 Development with C++ ODBC Wrappers...74 Development with ADO and OLE DB SDK...75 ADO...75 OLE DB...75 Chapter 6: Distributing the Branded ODBC Drivers...77 Overview of Installation

7 Driver File Naming Conventions...78 Installation on Windows Clients...78 Using Microsoft Installation Tools...78 Copying Files...78 Adding Entries to Windows Registries...79 Adding Entries to the [ODBCINST.INI] Section of the Registry...79 Adding Entries to the [ODBC.INI] Section of the Registry...80 Enabling Users to Set Configuration Parameters...81 Installation on UNIX and Linux Clients...81 Copying Files...81 Adding System Information...81 Adding Entries to the odbcinst.ini File...82 Adding Entries to odbc.ini file...83 Enabling Users to Set Configuration Parameters...84 File Distribution for the Windows ODBC Drivers...84 Required Files to Distribute...84 Files You Must Distribute...84 Optional Files to Distribute...85 Files You May Distribute...85 Help Files...86 Online Books...86 Files You Must Not Distribute...86 Keys and Values...86 File Distribution for the UNIX and Linux ODBC Drivers...87 Required Files to Distribute...87 Files You Must Distribute...87 Optional Files to Distribute...88 Files You May Distribute...88 Help Files...89 Online Books...89 Files You Must Not Distribute...89 Appendix A: Third Party Acknowledgements...91 Index

8 8

9 Distributing Your DataDirect Cloud Drivers As an OEM Partner, you can distribute branded versions of the DataDirect Cloud Driver for JDBC and DataDirect Cloud Drivers for ODBC drivers with your product, providing your customers with the same performance and functionality offered by the commercial versions of the drivers. Distributing the DataDirect Cloud driver with your application involves the following processes: Branding the DataDirect Cloud Drivers on page 9 Managing User Accounts Using the User-Provisioning API on page 9 Branding the DataDirect Cloud Drivers Branding the standard commercial DataDirect Cloud Driver for JDBC and DataDirect Cloud Drivers for ODBC allows you to distribute the drivers with your application as closed, password-protected drivers. Branding creates a branded version of the driver files, which you can distribute. The DataDirect Cloud drivers include an installation program (or script, for UNIX/Linux) that enables you to install and brand from downloaded files or a network directory. In most cases, using the Progress DataDirect installer is a quick and efficient way to brand your drivers. However, you may prefer to use the OEM Branding Tool Kit. In some cases, you must first install the drivers, and then use the OEM Branding Tool Kit. This book is your guide to branding DataDirect Cloud Drivers. Managing User Accounts Using the User-Provisioning API As the DataDirect Cloud Administrator, you can manage user accounts for distributed drivers using the User-Provisioning API. The User-Provisioning API allows you to create, retrieve, update, and delete user accounts, and to manage entitlements, such as data stores and data transfer limit. The DataDirect Cloud Service Provider creates an account for the Administrator to manage user accounts and entitlements. For more information on using the User-Provisioning API, refer to User-Provisioning API in the DataDirect Cloud Management API User's Guide. 9

10 Chapter 1: Distributing Your DataDirect Cloud Drivers 10

11 Preface For details, see the following topics: About this Book Branding Your DataDirect Cloud Driver Using This Book Typographical Conventions Contacting Customer Support About this Book This book is for application developers who are distributing the DataDirect Cloud Driver for JDBC or the DataDirect Cloud Driver for ODBC from Progress DataDirect with their database applications. Branding Your DataDirect Cloud Driver In addition to the installer program, you use one of the following branding tools to convert the DataDirect Cloud drivers into branded drivers. The Branding Tool Kit for DataDirect Cloud for JDBC contains the DataDirect Cloud JDBC Branding Tool. The Branding Tool Kit for DataDirect Cloud for ODBC contains the DataDirect Cloud ODBC Branding Tool. 11

12 Preface The conversion into a branded format closes the driver and uniquely codes it. The driver is closed because the license file allows it to work only with your application, preventing it from being used with other ODBC or JDBC applications. The driver is uniquely coded because the DLLs or shared libraries are renamed and encoded with a special 2-character prefix that is unique to your application. This eliminates the possibility of conflicts with other ODBC or JDBC drivers. Using This Book This book contains the following information: Branding the JDBC Driver on page 17 explains how to brand DataDirect Cloud driver for JDBC using the product installer and standalone branding tool. Unlocking the Branded JDBC Driver on page 35 explains how to unlock the JDBC driver from the applications that you develop. Distributing the Branded JDBC Driver on page 37 explains which files you must distribute with your JDBC applications. Branding the ODBC Drivers on page 43 explains how to brand DataDirect Cloud drivers for ODBC using the product installer. Unlocking the ODBC Drivers on page 71 explains how to unlock drivers from the applications that you develop. Distributing the Branded ODBC Drivers on page 77 explains how to distribute the product files for installation with your application. In addition, the chapter explains which files you must distribute with your ODBC applications for Windows and for UNIX/Linux. Typographical Conventions This guide uses the following typographical conventions: italics Convention Explanation Introduces new terms with which you may not be familiar, and is used occasionally for emphasis. bold Emphasizes important information. Also indicates button, menu, and icon names on which you can act. For example, click Next. BOLD UPPERCASE Indicates keys or key combinations that you can use. For example, press the ENTER key. UPPERCASE Indicates SQL reserved words. monospace Indicates syntax examples, values that you specify, or results that you receive. 12

13 Preface Convention Explanation monospaced italics > Indicates names that are placeholders for values that you specify. For example, filename. Separates menus and their associated commands. For example, Select File > Copy means that you should select Copy from the File menu. / The slash also separates directory levels when specifying locations under UNIX. vertical rule Indicates an "OR" separator used to delineate items. brackets [ ] Indicates optional items. For example, in the following statement: SELECT [DISTINCT], DISTINCT is an optional keyword. Also indicates sections of the Windows Registry. braces { } Indicates that you must select one item. For example, {yes no} means that you must specify either yes or no. ellipsis... Indicates that the immediately preceding item can be repeated any number of times in succession. An ellipsis following a closing bracket indicates that all information in that unit can be repeated. Contacting Customer Support Progress DataDirect offers a variety of options to meet your customer support needs. Please visit our Web site for more details and for contact information: The Progress DataDirect Web site provides the latest support information through our global service network. The SupportLink program provides access to support contact details, tools, patches, and valuable information, including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletins and other information. When you contact us for assistance, please provide the following information: Your customer number or the serial number that corresponds to the product for which you are seeking support, or a case number if you have been provided one for your issue. If you do not have a SupportLink contract, the SupportLink representative assisting you will connect you with our Sales team. Your name, phone number, address, and organization. For a first-time call, you may be asked for full customer information, including location. The Progress DataDirect product and the version that you are using. The type and version of the operating system where you have installed your product. 13

14 Preface Any database, database version, third-party software, or other environment information required to understand the problem. A brief description of the problem, including, but not limited to, any error messages you have received, what steps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and so on. Depending on the complexity of the problem, you may be asked to submit an example or reproducible application so that the issue can be re-created. A description of what you have attempted to resolve the issue. If you have researched your issue on Web search engines, our Knowledgebase, or have tested additional configurations, applications, or other vendor products, you will want to carefully note everything you have already attempted. A simple assessment of how the severity of the issue is impacting your organization. August 2014, Version

15 I Distributing the JDBC Driver For details, see the following topics: Branding the JDBC Driver Unlocking the Branded JDBC Driver Distributing the Branded JDBC Driver 15

16 Part I: Distributing the JDBC Driver 16

17 1 Branding the JDBC Driver Branding the standard commercial DataDirect Cloud Driver for JDBC allows you to distribute the driver with your application as a closed, password-protected driver. Branding creates a branded version of the driver jar files, which you may distribute. The DataDirect Cloud Driver for JDBC includes an installation program (or script, for UNIX/Linux) that enables you to install and brand from downloaded files or a network directory. In most cases, using the Progress DataDirect installer is a quick and efficient way to brand your driver. However, in some cases, you may prefer to use the OEM Branding Tool Kit. For details, see the following topics: Branding the JDBC Driver in the Product Installer Branding the JDBC Driver Using the Standalone Tool Branding the JDBC Driver in the Product Installer The product installer allows you to brand the DataDirect Cloud for JDBC driver for distribution with your application. The conversion into the branded format codes the driver to work only with your application and creates uniquely named files to prevent conflicts with other JDBC drivers. If you prefer installing the files prior to conversion, consider using the OEM Branding Tool Kit. Before Branding the JDBC Driver in the Product Installer Note: The OEM Partners section of the Progress DataDirect Web site is password-protected. As part of your OEM agreement, Progress DataDirect provides you with the appropriate location and passwords for the site. 17

18 Chapter 1: Branding the JDBC Driver Before you brand the driver: Obtain the serial number and the license key provided by Progress DataDirect for branding the product: To find your serial number, go to the OEM Partners section of the Progress DataDirect Web site. Click the Current Licenses link. To request a license key, enter the serial number and your customer information on the Progress DataDirect Request Upgrade Web page: Register a 2-character file prefix through the OEM Partners section of the Progress DataDirect Web site. Use this registered file prefix during branding to avoid file name conflicts with other Progress DataDirect for JDBC drivers that may be installed on a user s system. If you already use a unique file prefix registered with Progress DataDirect, you can use that prefix. Register a password through the OEM Partners section of the Progress DataDirect Web site (a maximum of 24 characters). The password is case-sensitive. Use this registered password during branding to protect the drivers from being used by other applications. Verify that you have installed a J2SE 5 or higher Java Virtual Machine (JVM) on your system. Branding the Product (JDBC) The following procedure shows screen shots of an installation on a Windows system. UNIX/Linux installation screens and messages are similar. The installer for the standard commercial DataDirect Cloud Driver for JDBC allows you to brand the driver on a local drive on Windows and non-windows operating systems. Before beginning, choose an installer directory for the product installer. The installer allows you to choose a different directory to install the branded drivers. Important: The Java installer can be run on any platform, including Windows; however, if you run the Java installer on Windows, turn off User Account Controls or select a non-system directory as the installation directory. The Windows installer allows you to install the driver in the Program Files system directory on Windows without turning off User Account Controls. To brand the drivers on your local drive: 1. Download the Windows or Java installer from the location provided by Progress DataDirect: Windows: PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_WIN_INSTALL.exe Non-Windows: PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar 2. Perform the branding: If you prefer to use a Graphical User Interface (GUI), go to Branding the JDBC Driver Using the GUI on page 19 for instructions. If you prefer to use a command line, go to Branding the JDBC Driver Using the Command-Line (UNIX/Linux) on page 21 for instructions. 18

19 If you prefer to use a silent installation, go to Branding the JDBC Driver Using a Silent Installation on page 23 for instructions. Branding the JDBC Driver Using the GUI Before you begin, gather the information you need during the installation: The Branding Key assigned to you for specifically-licensed products and product features The branding prefix and password you registered on the OEM page The following procedure shows screen shots from an installation on a Windows system. UNIX/Linux installation screens and messages are similar. To brand the DataDirect Cloud Driver for JDBC using the GUI: 1. From the installer directory, double-click the installer file to start the installer. Windows: PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_WIN_INSTALL.exe UNIX/Linux: PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar The product Introduction window appears. Click Next. 2. The Install Type window appears. Select the OEM Installation option. Enter your Branding Key in the Branding Key field; then, click Next. 3. A Product Branding window appears, prompting you for branding information. 19

20 Chapter 1: Branding the JDBC Driver Provide the following information; then, click Next. Vendor File Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. (See Before Branding the JDBC Driver in the Product Installer on page 17 for details.) This prefix is added to the DataDirect Cloud for JDBC Jar file names. For example, if dx is your file prefix, ddcloud.jar becomes dxddcloud.jar. Vendor Package Prefix: Type a package prefix for the branded driver (maximum of 64 characters). To avoid package name conflicts, the package prefix should adhere to the package naming conventions defined in the Java Language Specification. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the driver jar file when you brand a driver. For example, if com.xyzcompany.xyzdivision is your package prefix, the driver class: com.ddtek.jdbc.ddcloud.ddclouddriver becomes: com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver Vendor Subprotocol Prefix: The driver is registered with a URL subprotocol of the form datadirect:ddcloud. To replace datadirect in the subprotocol with your company name, type a prefix (maximum of 32 characters) in this field. For example, if xyzcompany is your subprotocol prefix, the URL: jdbc:datadirect:ddcloud://mydb.com becomes: jdbc:xyzcompany:ddcloud://mydb.com Note: To register JDBC subprotocol names, contact Oracle. 20

21 Vendor Message Prefix: Type a message prefix (maximum of 32 characters). After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][DDCloud JDBC Driver] Object has been closed becomes: [xyzcompany][ddcloud JDBC Driver] Object has been closed Vendor Password: Type the password you registered through the OEM Partners section of the Progress DataDirect Web site. The password is case-sensitive. This password is locked into the branded drivers to prevent unauthorized applications from using the branded drivers. 4. In the Where Would You Like to Install? field, type the path of the product installation directory or click the Choose (...) button to browse to and select an installation directory. The default installation directory is: Windows: C:\Program Files\Progress\DataDirect\Cloud_for_JDBC_20 UNIX/Linux: /opt/progress/datadirect/cloud_for_jdbc_20 To restore the installation directory to its default setting, click Restore Default Folder. Then, click OK to return to the Choose Installation Directory window. 5. Verify that you have entered (or selected) the correct installation directory. Click Next to continue. Note: If you specify a directory that contains a previous installation of the driver, a warning message appears indicating that you can overwrite your existing installation or specify a different installation directory. 6. The Pre-Installation Summary window provides the opportunity for you to click back through the Setup windows and make any changes or corrections. When you are satisfied with your selections, click Install to begin the installation. 7. Click Done to exit the installer. Refer to the installation log file for a record of any problems that may have occurred during the installation. See Installation Log File (JDBC) on page 29 for details. Branding the JDBC Driver Using the Command-Line (UNIX/Linux) Using the command-line to brand the JDBC driver is only supported on UNIX/Linux platforms. To brand the DataDirect Cloud Driver for JDBC using the command-line: 1. At a command prompt, type the installation command java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -i console; then press ENTER: The installer prompts you to answer questions regarding the installation. To accept the default value, press ENTER. To return to the previous step, type back and press ENTER. 2. The Introduction step appears. Press ENTER. 3. The product license agreement appears. Press ENTER multiple times to page to the end of the agreement. At the end, you are asked to accept the agreement: Type Y to accept the license agreement and continue with the installation. Type N to end the installation. 21

22 Chapter 1: Branding the JDBC Driver Press ENTER to continue. 4. You are prompted for the type of installation. Type 2 for a licensed or OEM install and press ENTER. 5. You are prompted for the serial number and the IPE key for branding provided by Progress DataDirect. Type the serial number and press ENTER. Then, type the IPE key and press ENTER. 6. You are prompted for the vendor file prefix. Type the 2-character file prefix you registered through the OEM Partners section of the Progress DataDirect Web site and press ENTER. This prefix is added to the driver Jar file names. For example, if dx is your file prefix, ddcloud.jar becomes dxddcloud.jar. 7. You are prompted for the vendor package prefix. Type a package prefix for the branded drivers (maximum of 64 characters) and press ENTER. The vendor package prefix can have a maximum of 64 characters. To avoid package name conflicts, the package prefix should adhere to the package naming conventions defined in the Java Language Specification. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the driver jar file when you brand a driver. For example, if com.xyzcompany.xyzdivision is your package prefix, the driver class: com.ddtek.jdbc.ddcloud.ddclouddriver becomes: com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver 8. You are prompted for the vendor subprotocol prefix. Type a vendor subprotocol prefix and press ENTER. The driver is registered with a URL subprotocol of the form datadirect:ddcloud. To replace datadirect in the subprotocol with your company name, type a prefix (maximum of 32 characters) in this field. For example, if xyzcompany is your subprotocol prefix, the URL: jdbc:datadirect:ddcloud://mydb.com becomes: jdbc:xyzcompany:ddcloud://mydb.com To register JDBC subprotocol names, contact Oracle. 9. You are prompted for the vendor message prefix. Type a message prefix for the branded drivers (maximum of 32 characters) and press ENTER. After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][DDCloud JDBC Driver] Object has been closed becomes: [xyzcompany][ddcloud JDBC Driver] Object has been closed 10. You are prompted for the vendor password. Type the password you registered through the OEM Partners section of the Progress DataDirect Web site and press ENTER. The password is case-sensitive. This password is locked into the branded drivers to prevent unauthorized applications from using the branded drivers. 22

23 11. You are prompted for the directory to install the branded drivers. Type the full path to the directory and press ENTER. The default installation directory is /opt/progress/datadirect/cloud_for_jdbc_ You are prompted to confirm the installation directory. If the directory is correct, type y and press ENTER. Note: If you specify a directory that contains a previous installation of the driver, a warning message appears indicating that you can overwrite your existing installation or specify a different installation directory. 13. You are prompted to review the product name and branding directory. Press ENTER to continue. 14. If the branded drivers were successfully installed, a message appears confirming the installation. Press ENTER to exit the installer. Refer to the installation log file for a record of any problems that may have occurred during the installation. See Installation Log File (JDBC) on page 29 for details. Branding the JDBC Driver Using a Silent Installation The silent installation is useful if you want to create a response file that can be distributed and run on multiple computers to create an identical branded installation of the product on each computer. To perform the silent installation, you must distribute both the response file and the installation jar file, PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar. A silent installation requires performing the following steps: Creating the response file. You can create this file in either of the following ways: Using the installer. See Creating the Response File Using the Installer (JDBC) on page 23 for instructions. Using a text editor. See Creating a Response File Using a Text Editor (JDBC) on page 26 for instructions. Performing the silent installation. See Performing the Silent Installation (JDBC) on page 28 for instructions. Important: Your product license may limit the number of CPUs that can exist on the machine on which the product is installed. This limit also is imposed on any machine on which the silent installation is performed. If you need to upgrade your product license, contact your Progress DataDirect sales representative. Creating the Response File Using the Installer (JDBC) To brand drivers during a silent installation, you must first create a response file. Take the following steps to create a response file using the installer: 1. At a command prompt, type the command: java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -r response_file where response_file is the path and file name of the response file you want to create. You can specify an absolute or relative path. If the path is not specified, the specified file is created in the current working directory. 23

24 Chapter 1: Branding the JDBC Driver Windows Example: This example creates a response file named installer.properties in the C:\temp directory. java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -r C:\temp\installer.properties UNIX/Linux Example: This example creates a response file named installer.properties in the /install directory, which is relative to the current working directory. java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -r./install/installer.properties 2. The Progress DataDirect Cloud Driver for JDBC introduction window appears. Click Next. 3. The Install Type window appears. Select the OEM Installation option. Enter your Branding Key in the Branding Key field; then, click Next. 4. A Product Branding window appears, prompting you for branding information. 24

25 Provide the following information; then, click Next. Vendor File Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. (See Before Branding the JDBC Driver in the Product Installer on page 17 for details.) This prefix is added to the DataDirect Cloud for JDBC Jar file names. For example, if dx is your file prefix, ddcloud.jar becomes dxddcloud.jar. Vendor Package Prefix: Type a package prefix for the branded driver (maximum of 64 characters). To avoid package name conflicts, the package prefix should adhere to the package naming conventions defined in the Java Language Specification. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the driver jar file when you brand a driver. For example, if com.xyzcompany.xyzdivision is your package prefix, the driver class: com.ddtek.jdbc.ddcloud.ddclouddriver becomes: com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver Vendor Subprotocol Prefix: The driver is registered with a URL subprotocol of the form datadirect:ddcloud. To replace datadirect in the subprotocol with your company name, type a prefix (maximum of 32 characters) in this field. For example, if xyzcompany is your subprotocol prefix, the URL: jdbc:datadirect:ddcloud://mydb.com becomes: jdbc:xyzcompany:ddcloud://mydb.com Note: To register JDBC subprotocol names, contact Oracle. 25

26 Chapter 1: Branding the JDBC Driver Vendor Message Prefix: Type a message prefix (maximum of 32 characters). After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][DDCloud JDBC Driver] Object has been closed becomes: [xyzcompany][ddcloud JDBC Driver] Object has been closed Vendor Password: Type the password you registered through the OEM Partners section of the Progress DataDirect Web site. The password is case-sensitive. This password is locked into the branded drivers to prevent unauthorized applications from using the branded drivers. 5. In the Where Would You Like to Install? field, type the path of the directory where you want the branded driver installed or click the Choose (...) button to browse to and select an installation directory. The default installation directory is: Windows: C:\Program Files\Progress\DataDirect\Cloud_for_JDBC_20 UNIX/Linux: /opt/progress/datadirect/cloud_for_jdbc_20 To restore the installation directory to its default setting, click Restore Default Folder. Then, click OK to return to the Choose Installation Directory window. 6. Verify that you have entered (or selected) the correct installation directory, and click Next to continue. Note: If you specify a directory that contains a previous installation of the driver, a warning message appears indicating that you can overwrite your existing installation or specify a different installation directory. 7. A window appears allowing you to confirm your installation options. Click Previous to revise your choices, or click Install to continue with the installation. 8. Click Done to exit the installer. The response file is created in the directory you specified in Step Step 1 on page 23. To perform a silent installation using the response file, see Performing the Silent Installation (JDBC) on page 28 for instructions on running the response file. Creating a Response File Using a Text Editor (JDBC) To brand drivers during a silent installation, you must first create a response file. Using a text editor, create a response file with the following contents: ## Use the hash mark for comments in the file ## Values are placeholders for your data #Install Type # INSTALL_TYPE_STD=false INSTALL_TYPE_OEM=true #Product Branding # BRANDING_KEY=yyyyyyy BRANDING_FILE_PREFIX=aa 26

27 BRANDING_PACKAGE_PREFIX=bb BRANDING_SUBPROTOCOL_PREFIX=cc BRANDING_MESSAGE_PREFIX=dd BRANDING_PASSWORD=ee #Install Directory # USER_INSTALL_DIR=install_dir where: yyyyyyy aa bb is your branding key. is the 2-character branding file prefix you registered through the OEM Partners section of the Progress DataDirect Web site. (See Before Branding the JDBC Driver in the Product Installer on page 17 for details.) This prefix is added to the DataDirect Cloud for JDBC Jar file names. For example, if dx is your file prefix, ddcloud.jar becomes dxddcloud.jar. is the package prefix for the branded drivers (maximum of 64 characters). To avoid package name conflicts, the package prefix should adhere to the package naming conventions defined in the Java Language Specification. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the DataDirect Cloud for JDBC jar files when you brand the drivers. For example, if com.xyzcompany.xyzdivision is your package prefix, the driver class: com.ddtek.jdbc.ddcloud.ddclouddriver becomes: com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver cc is the vendor subprotocol prefix. The driver is registered with a URL subprotocol of the form datadirect:ddcloud. To replace datadirect in the subprotocol with your company name, type a prefix (maximum of 32 characters) in this field. For example, if xyzcompany is your subprotocol prefix, the URL: jdbc:datadirect:ddcloud://mydb.com becomes: jdbc:xyzcompany:ddcloud://server1:1433 Note: To register JDBC subprotocol names, contact Oracle. 27

28 Chapter 1: Branding the JDBC Driver dd is the message prefix for the branded drivers (maximum of 32 characters). After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][JDBC Cloud Driver] Object has been closed becomes: [xyzcompany][jdbc Cloud Driver] Object has been closed ee is the password you registered through the OEM Partners section of the Progress DataDirect Web site. The password is case-sensitive. This password is locked into the branded drivers to prevent unauthorized applications from using the branded drivers. install_dir is the installation directory for the branded product. An escape sequence is used to maintain directory structure, for example, C:\\Program Files\\Progress\\DataDirect\\Cloud_for_JDBC_20. To perform a silent installation using the response file, see Performing the Silent Installation (JDBC) on page 28 for instructions on running the response file. Performing the Silent Installation (JDBC) After creating a response file with the installer or a text editor, you can now perform the silent installation. 1. At a command prompt, change to the directory containing the PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar file. 2. Type the command: java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -f response_file -i silent where response_file is the path and file name of the response file created in Creating the Response File Using the Installer (JDBC) on page 23 or Creating a Response File Using a Text Editor (JDBC) on page 26. You can specify an absolute or relative path. If the path is not specified, the silent installation looks for the response file in the current working directory. Windows Example: This example performs a silent installation by running a response file named installer.properties in the C:\temp directory. java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -f C:\temp\installer.properties -i silent UNIX/Linux Example: 28

29 This example performs a silent installation by running a response file named installer.properties in the /install directory, which is relative to the current working directory. java -jar PROGRESS_DATADIRECT_CLOUD_JDBC_2.0_INSTALL.jar -f./install/installer.properties -i silent 3. The installation proceeds without any further user intervention or notification. Refer to the installation log file for a record of any problems that may have occurred during the installation. See Installation Log File (JDBC) on page 29 for details. Installation Log File (JDBC) If the installer successfully creates the product installation directory, the installer writes a log file named Progress_DataDirect_Cloud_Driver_for_JDBC.log to the following directory: Windows: install_dir\install\logs UNIX/Linux: install_dir/install/logs Examine the log file for a record of any problems that may have occurred during the installation. If a product installation fails completely, the installer does not create the product installation directory and writes a file named Progress_DataDirect_Cloud_Driver_for_JDBC_InstallFailed.txt in the machine s default temporary directory. If you need help interpreting the contents of these files, contact Progress DataDirect customer support. Branding Results (JDBC) Branding the driver performs the following actions: Installs a version of the product jar files and rar files using the vendor file prefix you specified. In addition, it installs a version of the DataDirect Test for JDBC startup files and configuration file for use with the branded driver. The branded files appear in the directory specified during branding. Changes the package names for the branded driver using the vendor package prefix you specified. Changes the vendor message prefix for driver-generated error messages so that messages will display the message prefix you specified. Locks the branded drivers with the vendor password you specified.your application must supply this password to unlock the branded driver. See Unlocking the Branded JDBC Driver on page 35 for instructions on unlocking the branded driver. Testing the Branded JDBC Driver with DataDirect Test See Using DataDirect Test with the Branded JDBC Driver on page 36 for instructions on testing the branded driver with DataDirect Test for JDBC. 29

30 Chapter 1: Branding the JDBC Driver Branding the JDBC Driver Using the Standalone Tool Using the standalone branding tool to brand the standard commercial DataDirect Cloud Driver for JDBC allows you to distribute the driver with your application as a closed, password-protected driver. Branding creates a branded version of the driver jar file in a directory that is specified during branding. You may distribute this branded file. Before Branding the JDBC Driver Using the Standalone Branding Tool Note: The OEM Partners section of the Progress DataDirect Web site is password-protected. As part of your OEM agreement, Progress DataDirect provides you with the appropriate location and passwords for the site. Before you brand the driver: Obtain the serial number and the license key provided by Progress DataDirect for branding the product: To find your serial number, go to the OEM Partners section of the Progress DataDirect Web site. Click the Current Licenses link. To request a license key, enter the serial number and your customer information on the Progress DataDirect Request Upgrade Web page: Register a 2-character file prefix through the OEM Partners section of the Progress DataDirect Web site. Use this registered file prefix during branding to avoid file name conflicts with other Progress DataDirect for JDBC drivers that may be installed on a user s system. If you already use a unique file prefix registered with Progress DataDirect, you can use that prefix. Register a password through the OEM Partners section of the Progress DataDirect Web site (a maximum of 24 characters). The password is case-sensitive. Use this registered password during branding to protect the drivers from being used by other applications. Download and install the Branding Tool from the Partners sections of the Progress DataDirect Web site. Instructions for downloading and installing the Branding Tool are provided on the Web site. If you want to brand the driver jar file in a directory other than the original installation directory, you must copy the entire /lib subdirectory from the original installation directory to the alternative directory before branding. Verify that you have installed a J2SE 5 or higher Java Virtual Machine (JVM) on your system. Branding Using the Standalone Branding Tool You can use the Branding Tool to brand the driver on a local drive on Windows and non-windows operating systems. 30

31 Note: If you want to brand both the DataDirect Cloud Driver for JDBC and the DataDirect Connect Series for JDBC drivers at the same time, take the following steps: Copy the contents of the \lib directory of the DataDirect Cloud Driver for JDBC into the \lib folder of the DataDirect Connect for JDBC installation directory. To enable DataDirect Test for JDBC with DataDirect Cloud, copy the following entries from the \install_dir\testforjdbc\config.txt file into the corresponding DataDirect Connect config.txt file: Add com.ddtek.jdbc.ddcloud.ddclouddriver to the Drivers: line, using a colon (:) as a separator between driver entries Add jdbc:datadirect:ddcloud://service.datadirectcloud.com;databasename=mysforce to the Databases: line, using a comma as a separator between driver entries. To brand the driver on your local drive, take the following steps: 1. Start the Branding Tool from the installation directory in either of the following ways: Double click the BrandingTool.jar file located in your installation directory. At the command prompt, type java -jar BrandingTool.jar and press Enter. The Progress DataDirect JDBC Branding Tool window appears. 31

32 Chapter 1: Branding the JDBC Driver 2. Provide the following information. Vendor File Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. This prefix is added to the DataDirect Cloud for JDBC Jar file names. For example, if dx is your file prefix, ddcloud.jar becomes dxddcloud.jar. Vendor Package Prefix: Type a package prefix for the branded driver (maximum of 64 characters). To avoid package name conflicts, the package prefix should adhere to the package naming conventions defined in the Java Language Specification. The package prefix replaces the DataDirect prefix of com.ddtek in all the classes within the driver jar file when you brand a driver. For example, if com.xyzcompany.xyzdivision is your package prefix, the driver class: com.ddtek.jdbc.ddcloud.ddclouddriver becomes: com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver Vendor Subprotocol Prefix: The driver is registered with a URL subprotocol of the form datadirect:ddcloud. To replace datadirect in the subprotocol with your company name, type a prefix (maximum of 32 characters) in this field. For example, if xyzcompany is your subprotocol prefix, the URL: jdbc:datadirect:ddcloud://mydb.com becomes: jdbc:xyzcompany:ddcloud://mydb.com Note: To register JDBC subprotocol names, contact Oracle. Vendor Message Prefix: Type a message prefix (maximum of 32 characters). After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][JDBC Cloud Driver] Object has been closed becomes: [xyzcompany][jdbc Cloud Driver] Object has been closed Vendor Password: Type the password you registered through the OEM Partners section of the Progress DataDirect Web site. The password is case-sensitive. This password is locked into the branded drivers to prevent unauthorized applications from using the branded drivers. Driver Directory: Type the full path to the installed driver or click the browse button (...) and navigate to the directory of the installed driver. The Branding Tool uses the driver in this directory to make branded copies. The branded copies are placed in this same directory. The default location of the driver jar file is install_dir/lib where install_dir is the installation directory. Branding Key: [Optional] Type the Branding Key assigned to you for specifically-licensed products and product features. If you enter more than one key, you must insert a space between each key. If you do not know the branding key(s) assigned to you, contact your account representative. 32

33 3. Click Brand to brand the drivers. The branding operation takes several seconds; a progress bar is displayed. 4. When branding is complete, a message window appears. Click OK to close the window. Then, click Quit to close the Branding Tool. The branded file appears in the same directory containing the original file. The default location of the driver jar file is install_dir/lib where install_dir is the installation directory. Note: If you branded DataDirect Cloud and DataDirect Connect Series for JDBC drivers at the same time, check the branded config.txt file to confirm that your changes are correct. You cannot use DataDirect Test with DataDirect Cloud driver without the correct changes. 33

34 Chapter 1: Branding the JDBC Driver 34

35 2 Unlocking the Branded JDBC Driver The branded DataDirect Cloud for JDBC driver can be unlocked only by JDBC applications that supply the case-sensitive password that was locked into the driver when it was branded. If an application tries to connect using the branded driver without supplying the correct password, the branded driver throws an exception and the connection fails. This chapter describes how to unlock the branded driver and provides examples. It also describes how you can unlock the branded driver for use with DataDirect Test for JDBC. For details, see the following topics: Unlocking the Branded Drivers Using DataDirect Test with the Branded JDBC Driver Unlocking the Branded Drivers To unlock the branded drivers, the application must cast the returned connection object to an ExtEmbeddedConnection object after calling Driver.connect(), DriverManager.getConnection(), PooledConnection.getConnection(), or DataSource.getConnection(). Next, the application must call the unlock method while passing the case-sensitive password specified during the branding process. When you unlock the branded drivers, you also unlock DataDirect Spy for JDBC, built-in functionality that allows you to track JDBC calls made by the driver on behalf of the application. The following code examples show how to unlock the drivers using connection URLs and data sources. The package prefix used in these examples is com.xyzcompany.xyzdivision the subprotocol prefix used is xyzcompany. Your application code must use the package prefix and subprotocol prefix specified when the drivers were branded. 35

36 Chapter 2: Unlocking the Branded JDBC Driver Unlocking a URL Connection import com.ddtek.jdbc.extensions.extembeddedconnection;... String url = "jdbc:xyzcompany:ddcloud://mydb.com;user=sa;password=xxx"; Class.forName ("com.xyzcompany.xyzdivision.jdbc.ddcloud.ddclouddriver"); Connection con = DriverManager.getConnection (url); // ExtEmbeddedConnection is a DataDirect-specific interface if (con instanceof ExtEmbeddedConnection) { ExtEmbeddedConnection embeddedcon = (ExtEmbeddedConnection)con; boolean unlocked = embeddedcon.unlock("xxx"); // "xxx" is the password } Unlocking a DataSource Connection import com.ddtek.jdbc.extensions.extembeddedconnection;... // Create a DataSource object DataSource ds = new com.xyzcompany.xyzdivision.jdbcx.ddcloud.ddclouddatasource(); // Set the DataSource properties... // DataSource may be persisted to JNDI as usual or used directly... Connection con = ds.getconnection(); // ExtEmbeddedConnection is a DataDirect-specific interface if (con instanceof ExtEmbeddedConnection) { ExtEmbeddedConnection embeddedcon = (ExtEmbeddedConnection)con; boolean unlocked = embeddedcon.unlock("xxx"); // "xxx" is the password } Using DataDirect Test with the Branded JDBC Driver DataDirect Test is a software component you can use while developing and testing your JDBC applications. It contains menu selections that correspond to specific JDBC functions, for example, connecting to a database or executing a SQL statement. DataDirect Test allows you to execute a single JDBC method or execute multiple JDBC methods simultaneously so that you can easily perform common tasks, such as returning result sets. In addition, you can display the results of all JDBC function calls in one window, while displaying fully commented Java JDBC code in an alternate window. When you brand the drivers, the Branding Tool creates the following startup files for DataDirect Test in the /jdbc/testforjdbc subdirectory in your product installation directory where xx is the vendor file prefix you specified during branding: xxtestforjdbc.bat (Windows) xxtestforjdbc.sh (UNIX/Linux) Use the appropriate file for your platform to start DataDirect Test. Refer to the Progress DataDirect Cloud documentation for information about configuring and using DataDirect Test. 36

37 3 Distributing the Branded JDBC Driver To distribute the branded DataDirect Cloud Driver for JDBC with your application, your application s installation program must install the branded driver, as well as your own files. You must provide your own installation program. The DataDirect Cloud Driver for JDBC installer cannot be used to install the branded driver. This chapter describes the features you should include in your installation program to install the branded drivers and the files that must be installed. For details, see the following topics: Installing the Branded JDBC Driver File Distribution for the JDBC Driver Installing the Branded JDBC Driver Important: Your branded driver will not operate without the requirements described in the following table. Table 1: Requirements for Branded Driver For Applications Using... JDBC 4.0 API JDBC 3.0 API JSR 114 Rowsets Product Requirements J2SE 5 or higher J2SE 5 or higher J2SE 5 or higher 37

38 Chapter 3: Distributing the Branded JDBC Driver JDBC 2.0 Core API For Applications Using... JDBC 2.0 Optional Package J2SE 5 or higher J2SE 5 or higher Product Requirements The following APIs are required and are supplied with the driver: JDBC Optional Package 2.0 JNDI 1.2 JDBC 1.22 API J2SE 5 or higher To install the branded driver, you must create an installation program that copies the branded jar files from your installation program directory to the client machine (see File Distribution for the JDBC Driver on page 38). Before your installation program copies a file to a client machine, it should verify if a file with the same name already exists and, if it does, compare the dates of both files. If this situation is detected, the installation program should ask users if they want to overwrite the existing file with the newer version. File Distribution for the JDBC Driver When distributing branded files, make sure that you know which files you are allowed to distribute and those that you are not allowed to distribute: For files that you are required to distribute for specific databases, see Files You Must Distribute on page 38. You must only distribute those files that you are contractually licensed to brand. For optional files that you may choose to distribute if you wish, see Optional Files on page 39. Some files require an additional license to distribute. For files that you are not permitted to distribute, see Files You Must Not Distribute on page 39. Files You Must Distribute The following table lists the files you must distribute for the DataDirect Cloud Driver for JDBC. The 2-character vendor file prefix you used to brand the files is represented in the file name by xx and the vendor package prefix is represented by packageprefix. The referenced directories are in your product installation directory. Table 2: Files You Must Distribute for DataDirect Cloud Driver for JDBC Directories and Files d2cjdbcreadme.txt Description An information file about the current release of DataDirect Cloud Driver for JDBC. 38

39 NOTICES.txt Directories and Files /lib/xxcloud.jar Description File containing third-party vendor license agreements. File containing the DataDirect Cloud driver and data source classes, specifically: packageprefix.jdbc.ddcloud.ddclouddriver packageprefix.jdbcx.ddcloud.ddclouddatasource packageprefix.jdbcx.ddcloud.ddclouddatasource40 as well as other DataDirect Cloud driver-specific classes and DataDirect Spy. This file must be on your CLASSPATH to use the DataDirect Cloud driver. Optional Files The following table lists files that you may choose to distribute if you wish. You must purchase an additional license from Progress DataDirect to distribute the DataDirect Connection Pool Manager. To purchase a license, contact your Progress DataDirect sales representative. The 2-character vendor file prefix that you used to brand the files is represented in the file name by xx. The referenced directories are in your product installation directory unless otherwise noted. Table 3: Optional Files for Distribution /help/*.* Directories and Files /pool manager/pool.jar Description The directories and files for the HTML-based online books for DataDirect Cloud Driver for JDBC. File containing classes used by the DataDirect Connection Pool Manager. Note: You must purchase an additional license from Progress DataDirect to distribute the DataDirect Connection Pool Manager. Files You Must Not Distribute The following table lists the files that you must not distribute. The referenced directories are in your product installation directory. Table 4: Files You Must Not Distribute Directories and Files /UninstallerData/*.* Description Files required to uninstall the DataDirect Cloud Driver for JDBC. 39

40 Chapter 3: Distributing the Branded JDBC Driver LicenseTool.jar /testforjdbc/*.* Directories and Files Description File required to extend evaluation of DataDirect Cloud Driver for JDBC. Directories and files for DataDirect Test components. 40

41 II Distributing the ODBC Drivers For details, see the following topics: Branding the ODBC Drivers Unlocking the ODBC Drivers Distributing the Branded ODBC Drivers 41

42 Part II: Distributing the ODBC Drivers 42

43 4 Branding the ODBC Drivers The conversion into a branded format closes the drivers and uniquely codes them. The drivers are closed because the license file allows them to work only with your application, preventing them from being used with other ODBC or ADO applications. The drivers are uniquely coded because the DLLs or shared libraries are renamed and encoded with a special 2-character prefix that is unique to your application. This eliminates the possibility of conflicts with other ODBC drivers or ADO providers. The DataDirect Cloud drivers for ODBC include an installation program (or script, for UNIX/Linux) that enables you to install and brand from downloaded files or a network directory. In most cases, using the DataDirect Cloud installer is a quick and efficient way to brand your drivers. In some cases, you must first install the drivers, and then use the OEM Branding Tool Kit. Refer to the DataDirect Cloud Documentation for installation requirements and other information. The OEM Branding Tool Kit can be used to brand the DataDirect Cloud drivers for ODBC on all supported platforms. Important: Although you may brand more drivers than you plan to distribute, you must distribute only the branded drivers for which you have contracted with Progress DataDirect. For details, see the following topics: Branding the ODBC Drivers in the Product Installer Branding the ODBC Drivers Using the Standalone Branding Tool 43

44 Chapter 4: Branding the ODBC Drivers Branding the ODBC Drivers in the Product Installer Branding the standard commercial DataDirect Cloud Drivers for ODBC allows you to distribute the driver with your application as a closed, password-protected driver. In most cases, using the Progress DataDirect installer is a quick and efficient way to brand your driver. You can brand the driver using the product installer or the standalone Branding Tool Kit. The installation renames the driver files, creates license files, and encodes them with a 2-character prefix of your choosing. The default prefix for the 32-bit driver file name is IV; for 64-bit driver file names, the default is DD. The prefix you enter replaces these default characters, for example, ggd2cnn.dll if you enter gg as the prefix and nn represents the driver level number. Refer to the DataDirect Cloud Documentation for installation requirements and configuration information. Note: In some cases, you prefer to use the OEM Branding Tool Kit. Begin with Branding the ODBC Drivers Using the Standalone Branding Tool on page 62 for instructions about the first step in the branding process for this driver. Before Branding Note: The OEM Partners section of the Progress DataDirect Web site is password-protected. As part of your OEM agreement, Progress DataDirect provides you with the appropriate location and passwords for the site. Before you brand the drivers: Register a 24-character password through the Progress DataDirect Web site. The password you enter during branding is locked into your drivers. Your password must be a maximum of 24 characters of 7-bit ASCII values. If you enter fewer than 24 characters, the missing characters are automatically padded as uppercase Qs. For example, if you enter: DATAD1RECT the password is automatically padded with Qs as follows: DATAD1RECTQQQQQQQQQQQQQQ Important: It is important to register your password with Progress DataDirect so that you always have a resource from which to retrieve it. Register for a 2-character prefix through the Progress DataDirect Web site to avoid file name conflicts with other DataDirect Cloud Drivers for ODBC that may be installed on a user s system. We recommend that you register a prefix using the following characters: a-z and 0-9 with special characters that are valid for file names in your operating system, such as underscore (_) or the dollar sign ($). Invalid characters for file names on Windows are \ / : *? < >. Branded DataDirect OEM 32- and 64-bit drivers have the same file names except for this prefix. Using the same prefix among different DataDirect Cloud Drivers for ODBC can cause conflicts. For example, if you already have a registered prefix for branding 32-bit DataDirect Cloud Drivers for ODBC, you should register for a second unique prefix for the 64-bit drivers to avoid file naming conflicts. If you have registered signatures for DataDirect Connect for ODBC and DataDirect Connect64 for ODBC, you can use them to brand the DataDirect Cloud 32-bit and 64-bit ODBC drivers. 44

45 The branding process encodes the 2-character prefix into the case-insensitive license file. The process creates a closed driver that can be used only with your product. Attempts to use the driver with any other product cause an error message to be displayed. The 2-character prefix is recorded in the license file name following the default file prefix; for example, if you enter gg as the prefix, the 32-bit license file name becomes IVGG.LIC. Table 5: Default License Files Driver DataDirect Cloud (32-bit) DataDirect Cloud (64-bit) Default File Name (Created during branding) (Created during branding) IVGG.LIC DDGG.LIC Branded Example To invoke your drivers after branding, an application must unlock your driver license file with the correct password. This password protects your drivers from being used by other applications. The password is case-sensitive; therefore, pay particular attention when mixing uppercase and lowercase letters in the password. Note: When you use your password to invoke the drivers from your applications, you must type all 24 characters, including any padded Qs. Branding the ODBC Drivers on Windows The installer allows you to brand the drivers on a local drive on Windows operating systems. To brand the drivers on your local drive: 1. Download the Windows installer for your product from the location provided by Progress DataDirect: PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_WIN_XX_INSTALL.exe 2. Install the product with branding: If you prefer to use a Graphical User Interface (GUI), go to Branding the ODBC Drivers Using the GUI on page 45 for instructions. If you prefer to use a silent installation, go to Branding the ODBC Drivers Using the Silent Installer on page 48 for instructions. Branding the ODBC Drivers Using the GUI Before you begin, gather the information you need during the installation: The Branding Key assigned to you for specifically-licensed products and product features The branding prefix and password you registered on the OEM page To brand the DataDirect Cloud Driver for ODBC using the GUI: 1. From the installer directory, double-click the PROGRESS_DATADIRECT_CLOUD_2.0_WIN_NN_INSTALL.exe installer file to start the installer. 45

46 Chapter 4: Branding the ODBC Drivers The product Introduction window appears. Click Next. 2. The License Agreement window appears. Make sure that you read and understand the license agreement. To continue with the installation, select the I accept the terms of the License Agreement option; then, click Next. 3. The Install Type window appears. Select the OEM Installation option. Enter your Branding Key in the Branding Key field; then, click Next. 4. A Product Branding window appears, prompting you for branding information. 46

47 Provide the following information; then, click Next. New Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before Branding on page 44 for details. For example, if you brand the driver with the prefix gf, the Branding Tool renames the driver file to gfd2cnn.dll. Company Name: Type your company name. This name is used in the license file and appears on the Version tab when displaying the properties of a DLL. The restrictions are: The field is case-sensitive. A maximum of 127 characters is allowed. Product Name: Type your product name. The restrictions are: The field is case-sensitive. A maximum of 63 characters is allowed. Password: Type the password you registered through the Partners section of the Progress DataDirect Web site. The password is case-sensitive. If you enter fewer than 24 characters, the password is automatically padded with uppercase Qs. This password is locked into the branded driver license file to prevent unauthorized applications from using the branded drivers. Message Prefix: Type an error message prefix for the branded drivers. The restrictions are: The field is case-sensitive. A maximum of 30 characters is allowed. After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][ODBC Cloud Driver] Object has been closed becomes: 47

48 Chapter 4: Branding the ODBC Drivers [xyzcompany][odbc Cloud Driver] Object has been closed Branding Suffix: (Optional) Type a branding suffix for the branded driver. The suffix can consist of a maximum of two numeric characters. After branding, the driver file names are displayed with this suffix. For example, if you brand the driver with the prefix gf and the branding suffix of 17, the driver file is renamed as gfd2c17.dll. 5. In the Where Would You Like to Install? field, type the path, including the drive letter, of the product installation directory or click the Choose (...) button to browse to and select an installation directory. For the 32-bit driver on a 64-bit machine, the default is: C:\Program Files (x86)\progress\datadirect\cloud_for_odbc_20 For all other installations, the default is: C:\Program Files\Progress\DataDirect\Cloud_for_ODBC_20 Verify that you have entered (or selected) the correct installation directory. Click Next to continue. Note: If you specify a directory that contains a previous installation of the driver, a warning message appears. You must install the drivers in the same installation directory. To restore the installation directory to its default setting, click Restore Default Folder. Then, click OK to return to the Choose Installation Directory window. Click Next. The Pre-Installation Summary window appears. 6. The Pre-Installation Summary window provides the opportunity for you to click back through the Setup windows and make any changes or corrections. When you are satisfied with your installation or branding option selections, click Install to begin the installation. 7. Click Done to exit the installer. This completes the installation and branding of the driver. Branding the ODBC Drivers Using the Silent Installer The installer program provides a command-line option for silent installations. The silent installation is useful for system administrators who want to create a batch file to execute multiple identical installations of the drivers. A silent installation requires performing the following steps: Creating the response file. You can create the response file in either of the following ways: Using the installer. See Creating a Response File for the ODBC Drivers Using the Installer on page 48 for instructions. Using a text editor. See Creating a Response File for the ODBC Drivers Using a Text Editor on page 49 for instructions. Performing the silent installation. See Performing the Silent Installation on page 51 for instructions. Creating a Response File for the ODBC Drivers Using the Installer To create a response file using the installer: 48

49 1. At a command prompt, type the command: installer_file -r response_file where installer_file is the file name for the installer program. response_file is the path and file name of the response file you want to create. You must specify an absolute path, with the path and file name enclosed in double quotation marks. This example creates a response file named installer.properties in the C:\temp directory. PROGRESS_DATADIRECT_CLOUD_2.0_WIN_64_INSTALL.exe -r "C:\temp\installer.properties" The Introduction window for the product installation appears. Click Next. 2. Continue at Step 1 on page 45 in Branding the ODBC Drivers Using the GUI. When the installation is complete, the branded drivers are installed, and the response file is created in the directory you specified in Step 1 on page 49. See Performing the Silent Installation on page 51 for instructions on running the response file. Creating a Response File for the ODBC Drivers Using a Text Editor Use a text editor to create a response file for the DataDirect Cloud driver with the following contents: ## Use the hash mark for comments in the file ## Values are placeholders for your data #Install Type # BRANDING_KEY= INSTALL_TYPE_STD=false INSTALL_TYPE_OEM=true #Product Branding # BRANDING_PREFIX=mb BRANDING_COMPANY_NAME=MyCompany BRANDING_PRODUCT_NAME=widgets BRANDING_PASSWORD=mybrandingpassword BRANDING_MESSAGE_PREFIX=xyzcompany BRANDING_SUFFIX= BRANDING_KEY= #Install Directory # USER_INSTALL_DIR_GUI_INPUT=C:\\temp\\Cloud_for_ODBC_20 #Create Default Data Source # INSTALL_OPTIONS_CREATE=0 where: 49

50 Chapter 4: Branding the ODBC Drivers BRANDING_PREFIX specifies the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before Branding on page 44 for details. For example, if you brand the DataDirect Cloud driver with the prefix mb, the Branding Tool renames this file to mbd2cnn.dll. BRANDING_COMPANY_NAME specifies your company name. By default, the company name that you entered on the Product Registration window is displayed. This name is used in the license file and appears on the Version tab when displaying the properties of a DLL. The restrictions are: The field is case-sensitive. A maximum of 127 characters is allowed. BRANDING_Product_Name specifies your product name. The restrictions are: The product name is case-sensitive. A maximum of 63 characters is allowed. BRANDING_PASSWORD specifies the password you registered through the Partners section of the Progress DataDirect Web site. The password is case-sensitive. If you enter fewer than 24 characters, the password is automatically padded with uppercase Qs. This password is locked into the branded driver license file to prevent unauthorized applications from using the branded drivers. BRANDING_MESSAGE_PREFIX specifies an error message prefix for the branded drivers. The restrictions are: The field is case-sensitive. A maximum of 30 characters is allowed. After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][ODBC CLOUD Driver] Object has been closed becomes: [xyzcompany][odbc CLOUD Driver] Object has been closed BRANDING_SUFFIX optionally specifies a branding suffix for the branded drivers. The suffix can consist of a maximum of two numeric characters (0 to 9). BRANDING_KEY specifies the branding key you received from Progress DataDirect. 50

51 USER_INSTALL_DIR_GUI_INPUT specifies the product installation directory. Notice that the colon (:) and backslash (\) special characters must be delimited with a backslash. If the path to the file contains a space, the space character must also be delimited. INSTALL_OPTIONS_CREATE specifies whether to create default data sources. Type 1 if you want to create default data sources or 0 if you do not want to create default data sources. See Performing the Silent Installation on page 51 for instructions on running the response file. Performing the Silent Installation To perform a silent installation: 1. Download the product zip file from the location provided by Progress DataDirect when you purchased the software. 2. Use a file compression utility such as WinZip and extract the file to a temporary directory, for example: C:\TEMP 3. At a command prompt, change to the directory containing the installer program file. 4. Type the command: installer_file i silent f "response_file" where: installer_file is the file name of the installer program. response_file is the path and file name of the response file created in Creating a Response File for the ODBC Drivers Using the Installer on page 48 or Creating a Response File for the ODBC Drivers Using a Text Editor on page 49. You must specify an absolute path, with the path and file name enclosed in double quotation marks. The following example performs a silent installation by running a response file named installer.properties, which is located in the C:\temp directory. PROGRESS_DATADIRECT_CLOUD_2.0_WIN_64_INSTALL.exe i silent f "C:\temp\installer.properties" 5. The installation proceeds without any further user intervention or notification. Refer to the installation log file for a record of any problems that may have occurred during the installation. See The Silent Installation Log File (ODBC) on page 52 for details. 51

52 Chapter 4: Branding the ODBC Drivers The Silent Installation Log File (ODBC) If the installer successfully creates the product installation directory, the installer writes a log file in the product installation directory. Examine the log file for a record of any problems that may have occurred during the installation. The installation log file name is one of the following: Progress_DataDirect_Cloud_Driver_for_ODBC_-_32_bit.log Progress_DataDirect_Cloud_Driver_for_ODBC_-_64_bit.log If the installation fails completely, the installer does not create the installation directory and writes a file named Progress_DataDirect_Cloud_Driver_for_ODBC_SilentInstallFailed.txt in the machine s default temporary directory (%TEMP%). If you need help interpreting the contents of these files, contact Progress DataDirect Customer Support. Branding the ODBC Driver on UNIX and Linux The installer enables you to brand the driver. After verifying your product key, you will be prompted for the company name, branding password, and other information. Note: The following steps reflect the messages displayed when installing on AIX. If you are installing on a different UNIX or Linux platform version, the name of that platform is substituted. To install the DataDirect Cloud driver from downloaded files: 1. Download the installer file for your product from the location provided by Progress DataDirect. For example, the file for a 32-bit AIX installation is PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_AIX_32_INSTALL.bin. 2. Install the product with branding: If you prefer to use a Graphical User Interface (GUI), go to Branding the Drivers in the GUI on UNIX and Linux on page 52 for instructions. If you prefer to use a command line, go to Branding the Drivers on UNIX and Linux Using the Command-Line Installer on page 55 for instructions. If you prefer to use a silent installation, go to Branding the ODBC Drivers Using the Silent Installer on page 57 for instructions. Branding the Drivers in the GUI on UNIX and Linux Before you begin: Gather the information you need during the installation: The Branding Key assigned to you for specifically-licensed products and product features The branding prefix and password you registered on the OEM page (Optional) The branding suffix to identify the release version Ensure that the PATH environment variable includes the path to a JRE 1.6 or newer. To brand the DataDirect Cloud Driver for ODBC using the GUI: 52

53 1. From the installer directory, double-click the executable file (for example, PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_AIX_NN_INSTALL.bin) to start the installer: The product Introduction window appears. Click Next. 2. The Install Type window appears. Select the OEM Installation option. Enter your branding key; then click Next to enter your product branding information. 3. A Product Branding window appears, prompting you for branding information. 53

54 Chapter 4: Branding the ODBC Drivers Provide the following information; then, click Next. New Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before Branding on page 44 for details. For example, if you brand the driver with the prefix gf, the Branding Tool renames this file to gfd2cnn.dll. Company Name: Type your company name. By default, the company name that you entered on the Product Registration window is displayed. This name is used in the license file and appears on the Version tab when displaying the properties of a DLL. The restrictions are: The field is case-sensitive. A maximum of 127 characters is allowed. Product Name: Type your product name. The restrictions are: The field is case-sensitive. A maximum of 63 characters is allowed. Password: Type the password you registered through the Partners section of the Progress DataDirect Web site. The password is case-sensitive. If you enter fewer than 24 characters, the password is automatically padded with uppercase Qs. This password is locked into the branded driver license file to prevent unauthorized applications from using the branded drivers. Message Prefix: Type an error message prefix for the branded drivers. The restrictions are: The field is case-sensitive. A maximum of 30 characters is allowed. After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][ODBC Cloud Driver] Object has been closed 54

55 becomes: [xyzcompany][odbc Cloud Driver] Object has been closed Branding Suffix: (Optional) Type a branding suffix for the branded drivers. The suffix can consist of a maximum of two numeric characters (0 to 9). After branding, the driver file names are displayed with this suffix. For example, if you brand the driver with the prefix gf and the branding suffix 17, the files are renamed as gfd2c17.dll. 4. In the Where Would You Like to Install? field, type the path of the product installation directory or click the Choose (...) button to browse to and select an installation directory. The default value for the installation directory for 32-bit Cloud driver is /opt/progress/datadirect/cloud_for_odbc_2.0. Verify that you have entered (or selected) the correct installation directory. Click Next to continue. Note: If you specify a directory that contains a previous installation of the driver, a warning message appears. You must install the drivers in the same installation directory. To restore the installation directory to its default setting, click Restore Default Folder. Then, click OK to return to the Choose Installation Directory window. Click Next. The Pre-Installation Summary window appears. 5. The Pre-Installation Summary window provides the opportunity for you to click back through the Setup windows and make any changes or corrections. When you are satisfied with your installation or branding option selections, click Install to begin the installation. 6. Click Done to exit the installer. This completes the installation. Verify branding by entering: demoodbc -uid user_name -pwd password data_source_name. For example: installdir/demo/demoodbc -uid johndoe -pwd secret DataSource3 Note: If the branding was successful, a license error message is returned because the demoodbc program does not use the new password and license file name that was used in the branding process. You can disregard this message. Branding the Drivers on UNIX and Linux Using the Command-Line Installer The installer enables you to brand the drivers. After verifying your product key, you will be prompted for the company name, branding password, and other information. Note: The following steps reflect the messages displayed when installing on AIX. If you are installing on a different UNIX or Linux platform version, the name of that platform is substituted. To install the Progress DataDirect Drivers for ODBC from downloaded files: 55

56 Chapter 4: Branding the ODBC Drivers 1. To run the installer program, switch to the temporary directory that contains the installer files and enter:./installer_filename i console Where: installer_filename is the full name of the installer's binary file you downloaded in Step 1 on page 52 of Branding the ODBC Driver on UNIX and Linux on page 52. For a 64-bit Linux installation, you would enter:./progress_datadirect_cloud_odbc_2.0_linux_64_install.bin -i console The installer prompts you to answer questions regarding the installation. To accept the default value, press ENTER. 2. The Introduction step appears. Press ENTER. 3. You are prompted for the type of installation. Enter 2. You are prompted to enter the IPE key that was provided by Progress DataDirect. Type the IPE key and then press ENTER. 4. You are prompted to enter the branding information for your driver: Prefix specifies the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before Branding on page 44 for details. When entering the 2-character prefix, be sure to enter it as uppercase if using letters. For example, if you brand the driver for Solaris with the prefix GF, the Branding Tool renames this file to gfd2cnn.so. Warning: Do not make up a prefix. Register for it through the Progress DataDirect Web site. Registering a prefix through the Web site guarantees that each OEM customer has a unique 2-character prefix. A unique prefix prevents DLL conflicts with other embedded drivers that may be on a user s system when your application is running. Company Name specifies the name of your company. This name is used in the license file and appears on the Version tab when displaying the properties of a DLL. The restrictions are: The name is case-sensitive. A maximum of 127 characters is allowed. Product Name specifies the name of your product. The restrictions are: The name is case-sensitive. A maximum of 63 characters is allowed. Password specifies the password that you registered with Progress DataDirect for invoking your driver files after you brand them. See Before Branding on page 44 for details. You must use this password in your applications to invoke the drivers. The password protects your branded drivers from being used by other applications. Message Prefix specifies an error message prefix for the branded drivers. The restrictions are: The name is case-sensitive. A maximum of 30 characters is allowed. 56

57 After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][Cloud ODBC Driver] Object has been closed becomes: [xyzcompany][cloud ODBC Driver] Object has been closed Branding Suffix optionally specifies a branding suffix for the branded drivers. The suffix can consist of a maximum of two numeric characters (0 to 9). After branding, the driver file names are displayed with this suffix. For example, if you brand the driver with the prefix GF and the branding suffix 17, the files are renamed as GFD2C17.so. 5. You are prompted to enter the absolute path to the installation directory. The default is: /opt/progress/datadirect/cloud_for_odbc_20 Note: For UNIX/Linux, if you do not have access to /opt, your home directory will be used in its place. 6. The Pre-Installation Summary step provides the opportunity for you to review the information you have entered, and you are prompted to accept or change the information: Press ENTER to accept the information and begin the installation. To change the information, type back; then, press ENTER. You are prompted for the information again. 7. After completion of the installation, a message appears indicating that you have installed the software successfully. Press ENTER to close the installer. 8. Verify branding by entering: demoodbc -uid user_name -pwd password data_source_name. For example: installdir/demo/demoodbc -uid johndoe -pwd secret DataSource3 Note: If the branding is successful, a license error message is returned because the demoodbc program does not use the new password and license file name that was used in the branding process. You can disregard this message. Important: Your product license may limit the number of CPUs that can exist on the machine on which the product is installed. If you need to upgrade your product license, contact your Progress DataDirect sales representative. Branding the ODBC Drivers Using the Silent Installer The installer program provides a command-line option for silent installations. The silent installation is useful for system administrators who want to create a batch file to execute multiple identical installations of the drivers. A silent installation requires performing the following steps: Creating the response file. You can create the response file in either of the following ways: 57

58 Chapter 4: Branding the ODBC Drivers Using the GUI installer. See Creating the Response File Using the GUI Installer (ODBC) on page 58 for instructions. Using the command-line installer. See Creating the Response File Using the Command-Line Installer (ODBC) on page 58 for instructions. Using a text editor. See Creating a Response File for the ODBC Drivers Using a Text Editor on page 49 for instructions. Performing the silent installation. See Performing the Silent Installation on page 51 for instructions. Creating the Response File Using the GUI Installer (ODBC) To create a response file using the installer: 1. At a command prompt, type the command:./installer_filename -r where installer_file is the file name for the installer program. config_file config_file is the path and file name of the response file you want to create. You must specify an absolute path, with the path and file name enclosed in double quotation marks. This example creates a config file named silent.cfg in the /opt/tmp directory. PROGRESS_DATADIRECT_CLOUD_2.0_WIN_64_INSTALL.bin -r "/opt/tmp/silent.config" The Introduction window for the product installation appears. Click Next. 2. Continue at Step 1 on page 53 in Branding the Drivers in the GUI on UNIX and Linux on page 52. When the installation is complete, the branded drivers are installed, and the response file is created in the directory you specified in Step 1 on page 58. See Performing the Silent Installation on page 61 for instructions on running the response file. Creating the Response File Using the Command-Line Installer (ODBC) To create a response file using the installer: 1. At a command prompt, type the command:./installer_filename -r where installer_file is the file name for the installer program. "response_file" -i console 58

59 response_file is the path and file name of the response file you want to create. You must specify an absolute path, with the path and file name enclosed in double quotation marks. This example creates a config file named silent.cfg in the /opt/tmp directory. PROGRESS_DATADIRECT_CLOUD_2.0_WIN_64_INSTALL.bin -r "/opt/tmp/silent.config" - i console The Introduction window for the product installation appears. Click Next. 2. Continue at Step 1 on page 56 in Branding the Drivers on UNIX and Linux Using the Command-Line Installer on page 55. When the installation is complete, the branded drivers are installed, and the response file is created in the directory you specified in Step 1 on page 58. See Performing the Silent Installation on page 61 for instructions on running the response file. Creating the Response File Using a Text Editor (ODBC) A response file is a text file that you create, for example, silent.cfg. This file must contain the arguments described in the following table.: ## Use the hash mark for comments in the file ## Values are placeholders for your data #Install Type # BRANDING_KEY= INSTALL_TYPE_STD=false INSTALL_TYPE_OEM=true #Product Branding # BRANDING_PREFIX=mb BRANDING_COMPANY_NAME=MyCompany BRANDING_PRODUCT_NAME=widgets BRANDING_PASSWORD=mybrandingpassword BRANDING_MESSAGE_PREFIX=xyzcompany BRANDING_SUFFIX= BRANDING_KEY= #Install Directory # USER_INSTALL_DIR_GUI_INPUT=C:\\temp\\Cloud_for_ODBC_20 #Create Default Data Source # INSTALL_OPTIONS_CREATE=0 where: BRANDING_PREFIX specifies the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before Branding on page 44 for details. For example, if you brand the DataDirect Cloud driver with the prefix mb, the Branding Tool renames this file to mbd2cnn.dll. 59

60 Chapter 4: Branding the ODBC Drivers BRANDING_COMPANY_NAME specifies your company name. By default, the company name that you entered on the Product Registration window is displayed. This name is used in the license file and appears on the Version tab when displaying the properties of a DLL. The restrictions are: The field is case-sensitive. A maximum of 127 characters is allowed. BRANDING_Product_Name specifies your product name. The restrictions are: The product name is case-sensitive. A maximum of 63 characters is allowed. BRANDING_PASSWORD specifies the password you registered through the Partners section of the Progress DataDirect Web site. The password is case-sensitive. If you enter fewer than 24 characters, the password is automatically padded with uppercase Qs. This password is locked into the branded driver license file to prevent unauthorized applications from using the branded drivers. BRANDING_MESSAGE PREFIX specifies an error message prefix for the branded drivers. The restrictions are: The field is case-sensitive. A maximum of 30 characters is allowed. After branding, driver error messages are displayed with this prefix. For example, if xyzcompany is your message prefix, the driver error message: [DataDirect][ODBC CLOUD Driver] Object has been closed becomes: [xyzcompany][odbc CLOUD Driver] Object has been closed BRANDING_SUFFIX optionally specifies a branding suffix for the branded drivers. The suffix can consist of a maximum of two numeric characters (0 to 9). BRANDING_KEY specifies the branding key you received from Progress DataDirect. USER_INSTALL_DIR_GUI_INPUT specifies the product installation directory. Notice that the colon (:) and backslash (\) special characters must be delimited with a backslash. If the path to the file contains a space, the space character must also be delimited. 60

61 INSTALL_OPTIONS_CREATE specifies whether to create default data sources. Type 1 if you want to create default data sources or 0 if you do not want to create default data sources. See Performing the Silent Installation on page 61 for instructions on running the response file. Performing the Silent Installation To perform a silent installation: 1. From a command-line prompt, change to the directory where you originally downloaded the installer program, which contains the installer-program file, or ensure that this directory is on your path. 2. Execute a silent installation: installer_file -f config_file where installer_file is the name of the binary executable file for the installer program. config_file is the location and name of the response file that you have created. If the response file is named silent.cfg and resides in the current working directory, you would enter the following for a 32-bit AIX installation: PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_AIX_32_INSTALL.bin -f silent.cfg You can also specify an absolute or relative path, for example: PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_AIX_32_INSTALL.bin -f /home/users/johndoe/silent.cfg or PROGRESS_DATADIRECT_CLOUD_ODBC_2.0_AIX_32_INSTALL.bin -f./install/silent.cfg 3. The installation proceeds without any further user intervention unless you enter an incorrect value on the command line or in the response file, in which case an error is displayed and the installer program aborts. You must correct the command line or silent installation response file and execute it again. Branding Results Branding the drivers performs the following actions: Installs a version of the driver files using the vendor file prefix you specified, and updates the installed odbc.ini and odbcinst.ini, as well as the license file. The branded files appear in the directory specified during branding. Changes the message prefix for driver-generated error messages so that messages will display the message prefix you specified. 61

62 Chapter 4: Branding the ODBC Drivers Locks the branded drivers with the vendor password you specified.your application must supply this password to unlock the branded drivers. See Unlocking the ODBC Drivers on page 71 for instructions on unlocking the branded drivers. Branding the ODBC Drivers Using the Standalone Branding Tool The product includes an installation program (or script, for UNIX/Linux) that enables you to install and brand from downloaded files or a network directory. In most cases, using the Progress DataDirect installer is a quick and efficient way to brand your driver. In some cases, you must first install the drivers, and then use the OEM Branding Tool Kit. The OEM Branding Tool Kit can be used to brand the DataDirect Cloud Drivers for ODBC on all supported platforms: Refer to the DataDirect Cloud Documentation for installation information. Note: The DataDirect Connect Series for ODBC drivers and the DataDirect Cloud Driver for ODBC must be installed in different directories. To brand the drivers at the same time, copy the files from the \drivers directory (Windows) or \lib directory (UNIX/Linux) of the DataDirect Cloud driver installation directory into the corresponding directory for the DataDirect Connect installation directory. About the Branding Tool The DataDirect ODBC OEM Driver Branding Tool renames the driver, creates license files, and encodes them with a 2-character prefix of your choosing. The default prefix for 32-bit driver file names is IV; for 64-bit driver file names, the default is DD. The prefix you enter replaces these default characters, for example, ggd2cnn.dll if you enter gg as the prefix and nn represents the driver level number. The branding process also encodes the 2-character prefix into the case-insensitive license file. The process creates a closed driver that can be used only with your product. Attempts to use the driver with any other product cause an error message to be displayed. The 2-character prefix is recorded in the license file name following the default file prefix; for example, if you enter gg as the prefix, the 32-bit license file name becomes IVGG.LIC. Table 6: Default License Files Driver DataDirect Cloud (32-bit) DataDirect Cloud (64-bit) Default File Name (Created during branding) (Created during branding) IVGG.LIC DDGG.LIC Branded Example Note: The branding tool in the Branding Tool Kit does not modify or overwrite your original driver and license files. It creates a branded copy of the files, which you can then distribute. Before You Use the Branding Tool Kit Before you can use the Branding Tool Kit, you must: 62

63 Install the current version the Progress DataDirect Cloud Driver for ODBC. Download and install the OEM Branding Tool Kit from the Progress DataDirect Web site. Instructions for downloading and installing the Branding Tool Kit are provided on the Web site. Register for a 2-character prefix through the Progress DataDirect Web site to avoid file name conflicts with other DataDirect Cloud Drivers for ODBC that may be installed on a user s system. We recommend that you register a prefix using the following characters: a-z and 0-9 with special characters that are valid for file names in your operating system, such as underscore (_) or the dollar sign ($). Invalid characters for file names on Windows are \ / : *? < >. Branded DataDirect OEM 32- and 64-bit drivers have the same file names except for this prefix. Using the same prefix among different DataDirect Cloud Drivers for ODBC can cause conflicts. For example, if you already have a registered prefix for branding DataDirect Cloud for ODBC 32-bit drivers, you should register for a second unique prefix for the 64-bit drivers to avoid file naming conflicts. If you have registered signatures for DataDirect Connect for ODBC and DataDirect Connect64 for ODBC, you can use them to brand the DataDirect Cloud 32-bit and 64-bit ODBC drivers. Register a 24-character password through the Progress DataDirect Web site so that you always have a resource from which to retrieve it. The password you enter in the DataDirect ODBC OEM Driver Branding Tool is locked into your drivers. Important: It is important to register your password with Progress DataDirect so that you always have a resource from which to retrieve it. To invoke your drivers after branding, an application must unlock your driver license file with the correct password. This password protects your drivers from being used by other applications. The password is case-sensitive; therefore, pay particular attention when mixing uppercase and lowercase letters in the password. Your password can be a maximum of 24 characters of 7-bit ASCII values. If you enter fewer than 24 characters, the missing characters are automatically padded as uppercase Qs. For example, if you enter: DATADIRECT the password is automatically padded with Qs as follows: DATADIRECTQQQQQQQQQQQQQQ Note: When you use your password to invoke the drivers from your applications, you must type all 24 characters, including any padded Qs. Branding the Drivers on Windows The Progress DataDirect ODBC Branding Tool is used to brand the Progress DataDirect Cloud for ODBC driver that you have already installed. 63

64 Chapter 4: Branding the ODBC Drivers Note that if you choose to distribute the optional Progress DataDirect enhanced trace DLL (IVTRCnn.DLL for 32-bit or DDTRCnn.DLL for 64-bit), you must do the following: 1. Move the trace DLL that was installed in your Windows system directory during the Progress DataDirect installation from the system directory to the \DRIVERS directory in your product installation directory. 2. Brand the drivers as described in the following section. 3. Move your original trace DLL back to your Windows system directory. Your installer must install the branded trace DLL to the user s Windows system directory or the DLL will not be available to the Windows ODBC Administrator. To brand drivers: 1. Start the DataDirect ODBC OEM Driver Branding Tool by navigating to the directory where you downloaded the OEM Branding Tool Kit. Then, double-click IVBRDnn.EXE for 32-bit drivers, or DDBRDnn.EXE for 64-bit drivers, where nn is the version number of the driver. When branding the DataDirect Cloud Driver for ODBC version 2.0, you must use the 7.1 version of the branding tool (DDBRND27.EXE) for the branding tool to work properly. The DataDirect ODBC OEM Driver Branding Tool dialog box appears: 2. Complete the fields as follows: Platform: The platform field is read-only. It displays the platform and DataDirect version supported by the Branding Tool. This must match the platform of the product that you have already installed. If the platforms are not the same, download the correct platform version of the Branding Tool from the Progress DataDirect Web site. New Prefix: Type the 2-character prefix that you registered with Progress DataDirect to encode the driver and license files. See Before You Use the Branding Tool Kit on page 62 for details. For example, if you brand the driver with the prefix gf, the Branding Tool renames this file to gfd2cnn.dll. 64