Advantage Ingres 2.6 Embedded Edition User Guide

Emma K McGrattan & Sam Somashekar

MAXIMUM SECURITY INFORMATION OF COMPUTER ASSOCIATES INTERNATIONAL INC. DO NOT COPY OR REPRODUCE ACCESS LIMITED TO CLEARED PERSONNEL ONLY STORE IN LOCKED FILE RETURN OR DESTROY IF ACCESS IS UNAUTHORIZED

Version: 1.72 Status: Complete

Last Revision: 8/20/2003 08:09:00 PM 2018年5月4日 Computer Associates —CONFIDENTIAL Embedded Ingres User Guide

ABSTRACT

The purpose of this document is to outline the information required to use Advantage Ingres 2.6 as a repository for other products within CA’s development organization. This document outlines the mechanics for including Ingres within other CA products. It will grow to include things like performance tuning and optimization. This document has been written by Ingres Development and not by the Ingres Documentation Group who would no doubt produce a far more polished document. History: 11-Nov-2000 (mcgem01) First Draft 06-Dec-2000 (mcgem01) Updated to include Terrence Clark’s FAQs and Sam Somashekar’s UNIX installation information 14-Dec-2000 (smejo01) Include Relational design document 07-Jan-2001 (mcgem01) Updated to include JDBC Driver and Server options. 16-Jan-2001 (mcgem01) Updated to correct truncated script in Appendix B. 14-Oct-2001 (mcgem01) Updated to reflect change in Level II organization. 08-Nov-2001 (mcgem01) Updated to include the /embed flag when generating a template response file. This will allow users, other than ‘ingres’ to successfully create a template. 08-Nov-2001 (forco02) Updated scrip to handle partitioned transaction log files. 28-Dec-2001 (somsa01) Updated for Advantage Ingres 2.6. 11-Jan-2002 (somsa01) Updated to include II_StartServiceSync(). 11-Mar-2002 (somsa01) Updated to reflect Ingres’ position on special characters. 28-Mar-2002 (somsa01) Updated to include II_GetIngresInstallSize().

Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

of 70 2018年5月4日 Computer Associates —CONFIDENTIAL Embedded Ingres User Guide

29-Aug-2002 (somsa01) Updated to include II_PrecheckInstallation(), as well as some other minor changes. 30-Aug-2002 (somsa01) Updated with Raymond Fan’s suggestions. 23-Sep-2002 (somsa01) Added 2.6/0207 as a valid Ingres version. 24-Sep-2002 (somsa01) Added “allusersshortcuts” as a valid response file option. 25-Sep-2002 (somsa01) Added the II_GCN…() function descriptions. 03-Oct-2002 (fanra01) Add descriptions for return values from II_IngresVersion and II_IngresVersionEx. 15-Oct-2002 (somsa01) Clarified parameter description of II_GetEnvVariable(). 01-Mar-2003 (somsa01) Added “installcalicensing” as a response file option. 02-Jul-2003 (somsa01) Added VDBA response file option. Also stated that Boolean values “1”,”0” and “Y”,”N” and “YES”,”NO” can be used in place of “TRUE”,”FALSE”. 08-Aug-2003 (karye01) Changed from using “uname –n” to using “iipmhost” to avoid potential problem with domain host names. 20-Aug-2003 (somsa01) Added 2.6/0305 as a valid Ingres version.

TABLE OF CONTENTS

1. INTRODUCTION 8

1.1 WHAT IS EMBEDDED INGRES? 8 1.2 LICENSING EMBEDDED INGRES 8 1.3 CHARACTERS SUPPORTED BY THE EMBEDDED INGRES INSTALLER 9 1.3.1 UNIX & Linux Operating Systems 9 1.3.2 Windows Operating Systems 9 1.4 REQUESTING HELP WITH EMBEDDED INGRES 9 1.5 PATCHING ADVANTAGE INGRES 2.6 EMBEDDED EDITION 10 1.6 REQUESTING NEW FEATURES IN EMBEDDED ADVANTAGE INGRES 2.6 10 2. PREPARING AN INSTALLATION IMAGE FOR WINDOWS NT/2000/XP/.NET 11

2.1 DETERMINING WHAT INGRES FILES NEED TO BE INCLUDED IN THE IMAGE 11 3. UNATTENDED INSTALLATION ON WINDOWS NT/2000/XP/.NET 12

3.1 INTRODUCTION 12 3.2 THE RESPONSE FILE FORMAT 12 3.3 CREATING A RESPONSE FILE TEMPLATE 12 3.4 INVOKING THE INGRES INSTALLER USING THE RESPONSE FILE 12 3.5 RESPONSE FILE OPTIONS 12 4. PREPARING AN INSTALLATION IMAGE FOR UNIX 17

4.1 OVERVIEW 17 4.2 INSTALLING THE MKIMAGE UTILITY 18 4.2.1 Extract the ‘install’ directory 18 4.2.2 Install CA Licensing 18 4.3 PREPARING A SUBSET INSTALLATION IMAGE 18 4.3.1 Environmental Settings 18 4.3.2 Preparing a Subset Installation Image from the Base Release 18 4.3.3 Preparing a Subset Installation Image from a Patch File 19 4.4 INSTALLING A SUBSET INSTALLATION IMAGE 19 4.4.1 Environmental Settings 19 4.4.2 Installing a Subset Installation Image Built From the Base Release 19 4.4.3 Installing a Subset Installation Image Built From a Patch File 20 5. BATCH INSTALLATION OF INGRES ON UNIX 21

5.1 INTRODUCTION 21 5.2 BEFORE YOU BEGIN 21 5.2.1 Environment Settings 21 5.2.2 Extract the ‘install’ directory 21 5.2.3 Install CA Licensing 21 5.2.4 Copying the files 21 5.2.5 Setting Ingres Environment Variables 23 5.2.6 Embedded Ingres specific environment variables 23 5.2.7 Setting up the Embedded Ingres Products 23 6. EMBEDDED INGRES API FOR WINDOWS NT/2000/XP/.NET 25

6.1 II_GETENVVARIABLE 26 6.1.1 Synopsis 26 6.1.2 Description 26 6.1.3 Parameters 26 6.1.4 Return Value 26 Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

6.2 II_GETINGRESINSTALLSIZE 27 6.2.1 Synopsis 27 6.2.2 Description 27 6.2.3 Parameters 27 6.2.4 Return Value 27 6.3 II_GETRESOURCE 28 6.3.1 Synopsis 28 6.3.2 Description 28 6.3.3 Parameters 28 6.3.4 Return Value 28 6.4 II_GETVERSION 29 6.4.1 Synopsis 29 6.4.2 Description 29 6.4.3 Parameters 29 6.4.4 Return Values 29 6.5 II_GCNAPI_MODIFYNODE 31 6.5.1 Synopsis 31 6.5.2 Description 31 6.5.3 Parameters 31 6.5.4 Return Value 32 6.6 II_GCNAPI_NODE_EXISTS 33 6.6.1 Synopsis 33 6.6.2 Description 33 6.6.3 Parameters 33 6.6.4 Return Value 33 6.7 II_GCNAPI_TESTNODE 34 6.7.1 Synopsis 34 6.7.2 Description 34 6.7.3 Parameters 34 6.7.4 Return Value 34 6.8 II_INGRESSERVICENAME 35 6.8.1 Synopsis 35 6.8.2 Description 35 6.8.3 Parameters 35 6.8.4 Return Values 35 6.9 II_INGRESVERSION 36 6.9.1 Synopsis 36 6.9.2 Description 36 6.9.3 Parameters 36 6.9.4 Return Values 36 6.10 II_INGRESVERSIONEX 37 6.10.1 Synopsis 37 6.10.2 Description 37 6.10.3 Parameters 37 6.10.4 Return Values 37 6.11 II_PINGGCN 38 6.11.1 Synopsis 38 6.11.2 Description 38 6.11.3 Parameters 38 6.11.4 Return Values 38 6.12 II_PRECHECKINSTALLATION 39 6.12.1 Synopsis 39 6.12.2 Description 39 6.12.3 Parameters 40 6.12.4 Return Values 40

6.13 II_SERVICESTARTED 42 6.13.1 Synopsis 42 6.13.2 Description 42 6.13.3 Parameters 42 6.13.4 Return Values 42 6.14 II_STARTSERVICE 43 6.14.1 Synopsis 43 6.14.2 Description 43 6.14.3 Parameters 43 6.14.4 Return Values 43 6.15 II_STARTSERVICESYNC 44 6.15.1 Synopsis 44 6.15.2 Description 44 6.15.3 Parameters 44 6.15.4 Return Values 44 6.16 II_STOPSERVICE 45 6.16.1 Synopsis 45 6.16.2 Description 45 6.16.3 Parameters 45 6.16.4 Return Values 45 6.17 II_TNG_VERSION 46 6.17.1 Synopsis 46 6.17.2 Description 46 6.17.3 Parameters 46 6.17.4 Return Values 46 7. INGRES CONFIGURATION SYSTEM 47

7.1 INTRODUCTION 47 7.2 GENERATING THE CONFIGURATION FILE 47 7.3 SETTING A CONFIGURATION PARAMETER FROM THE COMMAND LINE 47 7.4 GETTING THE VALUE OF A CONFIGURATION PARAMETER FROM THE COMMAND LINE 47 APPENDIX A. SAMPLE RESPONSE FILE 48

APPENDIX B. SAMPLE UNIX SETUP SCRIPT 50

APPENDIX C. FREQUENTLY ASKED QUESTIONS 57

WHEN SHOULD I USE OPENAPI? 57 HOW DO I REPORT A PROBLEM WITH EMBEDDED INGRES? 57 HOW DO I CREATE AN INGRES IMAGE CONTAINING ONLY THOSE FILES THAT I NEED TO SHIP WITH MY PRODUCT ON WINDOWS NT/2000/XP/.NET? 57 HOW DO I GENERATE A TEMPLATE RESPONSE FILE? 57 WHEN UPGRADING FROM OPENINGRES 1.2, A NUMBER OF DLL’S ARE LEFT BEHIND IN THE UTILITY DIRECTORY AND CAN CAUSE PROBLEMS. HOW DO I GET RID OF THEM? 57 SHOULD I ENABLE JOURNALING ON MY DATABASES? 57 SHOULD I PERFORM REGULAR CHECKPOINTS ON MY DATABASES? 58 SHOULD MY APPLICATION BE RESPONSIBLE FOR STARTING AND STOPPING INGRES? 58 HOW CAN I DESIGN MY TABLE SCHEMA TO MAKE INGRES WORK BEST FOR MY APPLICATION? 58 HOW SHOULD I MAINTAIN INGRES FROM MY APPLICATION’S POINT OF VIEW? 58 APPENDIX D. ADVANTAGE INGRES 2.6 NEW FEATURES 59

DBMS NEW FEATURES 59 Row Producing Procedures 59 Raw Location Support 59 Increased Maximum Size of Character Data-Types 59 Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

Concurrent Rollback 59 Hash Aggregation 59 Composite Histograms 60 Hash Join Support 60 Usermod Utility 60 Copydb Enhancements 60 XML Import/Export Utility 60 Alternative Template File for CPIO Database Checkpoints (UNIX only) 61 Context Sensitivity of Reserved Words 61 ODBC DRIVER ENHANCEMENTS 61 ODBC Support on UNIX 61 ODBC 3.5 Support 61 Microsoft Transaction Server Support 61 JDBC ENHANCEMENTS 61 ICE ENHANCEMENTS 61 ICE Development Environment 61 Ingres Journal Analyzer 62 Ingres Import Assistant 62 RMCMD Enhancements 62 APPENDIX E. SIMPLIFIED RELATIONAL DATABASE DESIGN 64

APPENDIX F. MAP OF SUPPORTED CHARACTERS 70

1. Introduction

1.1 What is Embedded Ingres? Embedded Ingres is a version of Ingres intended for use as a repository in CA products that require a database. There are three main differences between ‘Embedded’ and ‘Regular’ Ingres:  As a constituent component of TNG, Embedded Ingres can never hard fail because of a licensing problem. Messages will be written to the user’s Event Log or console as per the CA Licensing Standard. A new set of licensing component codes have been created for Embedded Ingres, these are detailed in section 1.2  In Windows environments, the requirement that there must be a user ‘ingres’ on the client’s PC when installing the server has been removed. Any user may install Embedded Ingres. In addition, the Ingres service can be started from the ‘System’ account on Windows NT/2000/XP/.NET  The default installation ID for an Embedded Ingres installation is WV on both UNIX and Windows In order to provide the ability to install Ingres from any account, Ingres security has been disabled. Issuing the following command will re-enable it: iisetres ii.%COMPUTERNAME%.setup.embed_user OFF While it is not recommended that Ingres security be bypassed, these changes have been made to meet the needs of various applications.

1.2 Licensing Embedded Ingres Embedded Ingres uses the CA Licensing Mechanism for user license validation. The relevant Ingres component codes should be included in the product’s license so that end- users do not have to separately license Ingres. Embedded Ingres will never hard fail on a license check, messages will be written to the user’s Event Log or console as per the CA Licensing Standard. The following table lists all available Embedded Ingres Component Codes.

Component Code Product Description 1H30 Ingres RDBMS 1XQ7 Ingres STAR Server 1JG2 Ingres Replicator 12GN Ingres ICE 1XRH Ingres Cluster Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

1VFU Tuxedo 1A3O CICS 1Q81 Encina 1ZXL OpenROAD Runtime 150F OpenROAD Development

1.3 Characters Supported by the Embedded Ingres Installer A number of questions have been raised as to what characters are permitted in machine names, user names and installation paths for Ingres 2.6; the following information should be used as a guide. Please also refer to Chapter 2 of the SQL Reference Guide for a list of valid characters in object names and delimited identifiers.

1.3.1 UNIX & Linux Operating Systems  System Names: Ingres supports any valid operating system machine name, i.e. computer names that contain ONLY alphanumeric characters and the hyphen (‘-‘).  User Names: Ingres supports alphanumeric characters, ‘@’, ‘#’, ‘$’, and ‘_’. The first character must be alphabetic. The maximum length is 32 characters.  Directory Names: In accordance with the restrictions imposed by many UNIX vendors, Ingres will ONLY support alphanumeric characters and the underscore (‘_’) in path names.

1.3.2 Windows Operating Systems  Computer Names: Because Ingres is most commonly deployed in heterogeneous environments, Embedded Ingres will support computer names that contain ONLY alphanumeric characters and the hyphen (‘-‘), per the standard.  User Names: Ingres supports alphanumeric characters, ‘@’, ‘#’, ‘$’, and ‘_’. The first character must be alphabetic. The maximum length is 32 characters.  Directory Names: Per the Microsoft standards, Ingres supports all characters except ‘?’, ‘|’, ‘*’, ‘<’, ‘>’, ‘’’, ‘”’, ‘\’, ‘/’.

1.4 Requesting Help with Embedded Ingres If problem is encountered with Embedded Ingres, an issue must be open in StarTrak in the Ingres ISL S 1 queue detailing all relevant information; this is then sent to the L1 support queue. When an issue is opened, the Ingres Level 2 Support Manager ([email protected]) should be notified, so that if the Level 1 support group determines that it is a bug, the issue can be given immediate attention. It is not sufficient to call or send an email to individual within Ingres Development or Support and expect the Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

problem to be fixed. Requests for help with application development or performance tuning should be directed to the Ingres Product Integration Group ([email protected])

1.5 Patching Advantage Ingres 2.6 Embedded Edition There will be a single version of Advantage Ingres 2.6 which can be installed as either ‘Embedded’ or ‘Regular’ Ingres. There will also be a single patch line. In Windows environments by the presence or absence of the /embed flag will determination whether Embedded or Regular Ingres is installed. On Unix, if the environment variable II_EMBED_INSTALL is set to “ON” then the Embedded version of Advantage Ingres is installed.

1.6 Requesting New Features in Embedded Advantage Ingres 2.6 Any requests for new functionality in Embedded Ingres should be addressed to the Ingres Product Carrier for Technology ([email protected]). No reasonable request will be refused. A SIR will be raised in the Ingres Bugs system so that the request is not overlooked and the request will be given a priority and a reference number assigned. If a request for additional functionality is made and a reference number is not provided, this should be followed up either by phone or email.

2. Preparing an Installation Image for Windows NT/2000/XP/.NET

2.1 Determining what Ingres files need to be included in the Image Space is often a concern when packaging a product; a utility has been provided called “makeimg” which can be used to create a template response file and to generate an image containing only the files required for the Ingres components selected.

This is the only supported way to create a cut down distribution of Ingres. It is the responsibility of the development team for the Embedded application to determine which Ingres components are needed and to create Ingres distribution using this utility.

Makeimg.exe

To generate the Ingres distribution perform the following steps:  Specify the location of the Advantage Ingres 2.6 Embedded Edition ISC file. The ISC file is used by the CA Installer to determine which files are installed as part of each product, the file size, program group, item names, etc. Use the “Browse…” button to locate this file. Normally, this file is called ingresii.isc and is located in the root directory of the Embedded Advantage Ingres 2.6 Image  Having located and selected the ingresii.isc file, “Source Image” and “Products to Be Included in the New Image” will be populated. Select from the products to be included in the new image list the Ingres products that are required for the installation  Generate a template response file by clicking the “Create Template Response File” button  Specify the location where the customized Ingres image will be created  Click the “Create Image” button and the distribution will be created. By clicking the “Show Extended Information” checkbox the progress of the file copy process can be monitored

3. Unattended Installation on Windows NT/2000/XP/.NET

3.1 Introduction One of the key requirements of Ingres as a repository is that its installation, initialization and configuration should be hidden from the end user. To facilitate this Embedded Ingres has the capability to be installed via a response file through which all configuration parameters and values are specified. This is done by invoking the installer with the /embed flag

3.2 The Response File Format The response file contains a fixed list of parameters followed by an equal sign and then a value which must be embedded in double quotes e.g. “FALSE”. A sample response file is included in Appendix A

3.3 Creating a Response File Template A template response file may be generated by using the command: install /embed /c This will invoke the Ingres installation wizard and any configuration information entered will be saved to a template response file. This does not install Ingres on the machine.

3.4 Invoking the Ingres Installer Using the Response File To invoke the Ingres installer with a response file use the command: install /embed /r

3.5 Response File Options The following table details the currently supported list of response file options. Note: Any reference to “TRUE” and “FALSE” values can also be substituted for by “1” and “0”, “Y” and “N”, and “YES” and “NO”.

Parameter Values Description allusersshortcuts “TRUE” or “FALSE” Determines whether Advantage Ingres shortcuts (if enabled) are created for all users (“TRUE”) or for just the current user (“FALSE”). The default is “TRUE”. charmap Full path and file Specifies the name of the character name to a character mapping file which defines valid description file characters for an installation. charset Any valid value for Specifies the value to be used for II_CHARSETxx the Ingres environment variable Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

Default is II_CHARSETxx “IBMPC850” In an upgrade the existing value is kept and should not be changed. checkpointdatabases “TRUE” or “FALSE” Determines whether user databases Default is “FALSE” are automatically checkpointed prior to being upgraded and immediately after a successful upgrade. If journaling is enabled, it will be disabled temporarily and enabled after the upgrade completes createicons “TRUE” or “FALSE” Determines whether the Advantage Default is “TRUE” Ingres II program group and associated icons are created during installation destroytxlogfile “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” transaction log file should be destroyed and a new one created in an upgrade. By default the existing log file size is retained duallogdir Directory path Specifies the location of the Default is secondary/dual transaction log file. %II_SYSTEM% It is recommended that this is on a different disk to the primary log enableDECNET “TRUE” or “FALSE” Determines whether the DECNET Default is “FALSE” protocol is initialized when the Communications Server starts enableduallogging “TRUE” or “FALSE” Determines whether dual logging is Default is “FALSE” enabled enableNETBIOS “TRUE” or “FALSE” Determines whether the NetBIOS Default is “FALSE” protocol is initialized when the Communications Server starts enableSPX “TRUE” or “FALSE” Determines whether the SPX Default is “FALSE” protocol is initialized when the Communications Server starts enablesql92 “TRUE” or “FALSE” Determines whether SQL-92 Default is “FALSE” compliance is enabled. enableTCPIP “TRUE” or “FALSE” Determines whether the TCP/IP Default is “TRUE” protocol is initialized when the Communications Server starts hidewindows “TRUE” or “FALSE” Determines whether the CA- Default is “FALSE” Installer copy file dialog and the Ingres setup dialog are displayed during installation II_SYSTEM Directory path Specifies the value of II_SYSTEM Default is Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

“%ProgramFiles %\CA\Advantage Ingres”C:\IngresII iicheckpointdir Directory path Specifies the value of Default is II_CHECKPOINT %II_SYSTEM% iidatabasedir Directory path Specifies the value of Default is II_DATABASE %II_SYSTEM% iidumpdir Directory path Specifies the value of II_DUMP Default is %II_SYSTEM% iijournaldir Directory path Specifies the value of Default is II_JOURNAL %II_SYSTEM% iiworkdir Directory path Specifies the value of II_WORK. Default is %II_SYSTEM% Ingres DBMS Server “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” DBMS is installed Ingres Embedded SQL/C “TRUE” or “FALSE” Determines whether Ingres Default is “FALSE” Embedded SQL/C is installed Ingres Embedded “TRUE” or “FALSE” Determines whether Ingres SQL/COBOL Default is “FALSE” Embedded SQL/COBOL is installed Ingres Online “TRUE” or “FALSE” Determines whether the Ingres On- Documentation Default is “FALSE” line documentation is installed Ingres Querying and “TRUE” or “FALSE” Determines whether Ingres Reporting Tools Default is “FALSE” Querying and Reporting Tools are installed Ingres/ICE “TRUE” or “FALSE” Determines whether Ingres ICE is Default is “FALSE” installed Ingres/Net “TRUE” or “FALSE” Determines whether Ingres Net is Default is “FALSE” installed Ingres/Replicator “TRUE” or “FALSE” Determines whether Ingres Default is “FALSE” Replicator is installed Ingres/Star “TRUE” or “FALSE” Determines whether Ingres Star is Default is “FALSE” installed Ingres/Vision “TRUE” or “FALSE” Determines whether Ingres Vision Default is “FALSE” is installed Ingres Visual DBA “TRUE” or “FALSE” Determines whether Ingres GUI Default is FALSE for tools is installed an Embedded install, TRUE for an Enterprise install ingresprestartuprunparams Parameter List Specifies the program arguments to Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

Default is none be passed to the program specified by the ingresprestartuprunprg parameter ingresprestartuprunprg Program Name Specifies the name of an Default is none executable, found in the path, which is to be run after the symbol table and config.dat have been generated, but before Ingres has been started for the first time to create iidbdb, etc installationcode Default for Embedded Specifies the value to be used for Ingres it is “WV” the Ingres environment variable For regular Ingres it is II_INSTALLATION “II” In an upgrade the existing value is kept installcalicensing “TRUE” or “FALSE Determines whether CA Licensing Default is “TRUE” is installed JDBC Driver “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” JDBC Driver component is installed JDBC Server “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” JDBC Server component is installed language Any valid Specifies the value of the Ingres II_LANGUAGE value environment variable Default is II_LANGUAGE. “ENGLISH” In an upgrade the existing value is kept leaveingresrunninginstalli “TRUE” or “FALSE” Determines whether Ingres is left ncomplete Default is “FALSE” running once the installation process completes logfilesize Any valid integer Specifies the size of the Ingres Default is “16” transaction log file in Megabytes OpenROAD Development “TRUE” or “FALSE” Determines whether the Default is “FALSE” OpenROAD Development component is installed OpenROAD Runtime “TRUE” or “FALSE” Determines whether the Default is “FALSE” OpenROAD Runtime component is installed primarylogdir Directory path Specifies the location of the Default is primary transaction log file %II_SYSTEM% To avoid contention it is recommended that this is on a different disk to II_SYSTEM remove_ingresodbc “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” ODBC driver and its DSN Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

definitions is removed during the installation process removeoldfiles “TRUE” or “FALSE” Determines whether the contents of Default is “FALSE” the: %II_SYSTEM%\ingres\bin %II_SYSTEM%\ingres\utility %II_SYSTEM%\ingres\vdba directories are removed by the installer in an upgrade serviceauto “TRUE” or “FALSE” Determines whether the Ingres Default is “FALSE” service is started automatically. servicepassword Password Specifies the ingres user’s password that is required when setting up the service If this is not specified, and the service is set to start automatically, the user must be instructed to set up the password before starting the service setup_ingresodbc “TRUE” or “FALSE” Determines whether the Ingres Default is “TRUE” ODBC driver is configured during installation terminal Any valid value for Specifies the value to be used for TERM_INGRES the Ingres environment variable enclosed in double TERM_INGRES quotes In an upgrade the existing value is Default is IBMPC kept timezone Any valid Specifies the value to be used for II_TIMEZONE_NAM the Ingres environment variable E value II_TIMEZONE_NAME. Default is the Ingres In an upgrade the existing value is timezone that most kept closely approximates to the OS timezone e.g.”NA-EASTERN” upgradeuserdatabases “TRUE” or “FALSE” Determines whether user databases Default is “FALSE” are automatically upgraded By default, only iidbdb is upgraded VDBA “TRUE” or “FALSE” Determines whether Ingres Visual Default is “FALSE” DBA is installed. This option is available for Embedded Ingres only

4. Preparing an Installation Image for UNIX

4.1 Overview Because space is often a concern when packaging a product, we have provided a utility called mkimage which can be used to create an image containing only the files required for the Ingres packages selected. This is the only supported way of distributing trimmed down versions of valid Ingres distributions. The utility will determine what packages are to be added, and will generate the image based on the specified packages. This utility can be used to prepare a subset installation image from either the distribution file (base release) or from a subsequent patch file for that release. The mkimage utility is executed from the command line. Usage details are as follows;

Usage: mkimage [flags]

Flags;

-r Build a subset distribution file which contains the packages in the list. -d dest_saveset Optionally used with -r to specify the name of the subset distribution file. If not used the default file name ./subset.tar is used. -s src_saveset Optionally used with -r to specify the name of the original distribution file. If not used the default file name ./ingres.tar is used. -l Lists all of the Ingres product feature names -c List Custom Packages. -p List Express Packages. -v Display descriptions of the packages in the list.

In the above represents a comma-separated list of product feature names.

4.2 Installing the mkimage Utility

4.2.1 Extract the ‘install’ directory Extract the ‘install’ directory from the ingres.tar file as the user ‘ingres’ cd /ingres tar -xvf /ingres.tar install

4.2.2 Install CA Licensing The following steps must be done as ‘root’ cd /ingres/install ./mklicense

4.3 Preparing a Subset Installation Image

4.3.1 Environmental Settings The following examples will assume that the mkimage utility has been installed. In each example we will generate a subset installation image for the Ingres Networked Client package (netclient).

4.3.2 Preparing a Subset Installation Image from the Base Release The following steps must be done as ‘ingres’ cd /ingres/install mkimage –r netclient –d /subset/netclient.tar –s /ingres.tar The /ingres/install/mkimage_log/pkg.log file will show that the following packages have been included; basic, config, net, netclient, setupsup, tm. These packages are all required in order to provide the Ingres Networked Client package, netclient.

4.3.3 Preparing a Subset Installation Image from a Patch File We will assume that p7121.tar.Z has been downloaded. We will further assume that this is a patch, which uses the utility/iiinstaller during installation. Please refer to the patch.doc for details. The following steps must be done as ‘ingres’ cd /ingres/install mkimage –r netclient –d /subset/net_p7121.tar.Z –s /p7121.tar.Z The /ingres/install/mkimage_log/pkg.log file will show that the following packages have been included; basic, config, net, netclient, setupsup, tm. These packages are all required in order to provide the Ingres Networked Client package, netclient.

4.4 Installing a Subset Installation Image

4.4.1 Environmental Settings The following environment variables must be set before invoking the Ingres installer II_SYSTEM – Installation destination directory Path – Append $II_SYSTEM/ingres/bin and $II_SYSTEM/ingres/utility Library Path – Append $II_SYSTEM/ingres/lib

4.4.2 Installing a Subset Installation Image Built From the Base Release The following steps must be done as ‘ingres’ cd $II_SYSTEM/ingres tar –xvf /netclient.tar install install/ingbuild Installation of the subset installation image, which was built from the base release, is exactly the same as the installation of the original distribution file. Express package installation images can be installed using the “Package Installation” option. The “Custom Install” will show the selected packages and the required sub-packages. These can be selected/deselected as normal. The netclient.tar can also be used for Batch Installation of Ingres for UNIX as described in the Embedded Ingres User Guide. Packages that are not included in the subset installation image will not appear when running ingbuild in interactive mode.

4.4.3 Installing a Subset Installation Image Built From a Patch File The following steps must be done as ‘ingres’ cd $II_SYSTEM/ingres zcat /net_p7121.tar.Z | tar –xvf – cd patch7121 ./utility/iiinstaller Installation of the patch is exactly the same as for the original patch. Details are in the patch.doc found in the patch7121 directory. All of the files, for all of the packages, included in the subset patch will be installed, regardless of whether the files exist in the target installation. It is the application developer’s responsibility to supply a subset patch, which matches the packages installed on the target installation. The plist file found in $II_SYSTEM/ingres/patch7121/utility contains details of the subset installation image and the patch upon which it was based. Do not modify this file. It is used by the utility/iiinstaller to install the subset patch files. The following is an example of the top of the plist file;

## Contents: REGENERATED Packing list ## ## Performed: Tue Jan 16 11:43:54 GMT 2001 ## Original Saveset: /dbms/patches/p7121.tar.Z ## Rebuilt Saveset: /dbms/patches/net_p7121.tar.Z ## Feature List: netclient ## ## ORIGINAL Packing list details below. ## ## Version: II 2.0/0001 (su4.us5/00) ## Patch: 7121 ## Task: build_plist ## Performed: 07-Dec-2000 16:25:37 ## Perfsdate: 2000-12-07-16:25:37 ##

5. Batch Installation of Ingres on UNIX

5.1 Introduction Ingres provides a flexible configuration to suit the needs of the client base; because of this, the Ingres installer has a lengthy dialog in which the user can specify particular configuration choices. Embedded Ingres provides a way for CA products to specify a basic set of installation options and install Ingres without embarking on this lengthy dialog

5.2 Before you begin

5.2.1 Environment Settings The following environment variables must be set before invoking the Ingres installer  II_SYSTEM – Installation destination directory  II_INSTALLATION – This is optional, but should be set to WV  Path – Append $II_SYSTEM/ingres/bin and $II_SYSTEM/ingres/utility  Library Path – Append $II_SYSTEM/ingres/lib

5.2.2 Extract the ‘install’ directory Extract the ‘install’ directory from the ingres.tar file cd $II_SYSTEM/ingres tar xvf /ingres.tar install

5.2.3 Install CA Licensing The following must be done as user ‘root’ cd $II_SYSTEM/ingres/install ./mklicense

5.2.4 Copying the files Use the ingbuild utility to copy the files from the distribution media Use the “-nosetup” option to avoid the shell script setup files from running in interactive mode Syntax: ingbuild [ flags ] [ ]

Flags: Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

-all Install all products -licensed Install all licensed products (default). -install= Install all products in the comma-separated list of product names. -products Display a list of the available products. -version[=] Display the version number of the installation or of each product in the comma-separated list. -express Run setup programs using default values. -nosetup Don't run setup programs.

Products: esql Embedded SQL pre-compilers custominst Full Installation oldmsg INGRES 6.x Compatible Message dbms Ingres Intelligent DBMS tuxedo Ingres DTP for Tuxedo dbmsnet Ingres Networked DBMS server dbmsstar Ingres Networked DBMS server w/STAR netclient Ingres Networked client standalone Ingres Stand-alone DBMS server c2audit Ingres C2 Security Auditing secure Ingres Enhanced Security ome Ingres Object Management bridge Ingres Protocol Bridge net Ingres Networking rep Ingres Replicator spatial Ingres Spatial Object Library ice Ingres Internet Commerce Enabled star Ingres Star Distributed DBMS qr_run Query and Reporting Runtime qr_tools Query and Reporting Tools tm Terminal Monitors

vispro VisionPro jdbc Ingres JDBC Server and JDBC Driver

To install Embedded Ingres as a user other than ‘ingres’ the environment variable II_EMBED_USER must be set. The value of this variable needs to be the user that will run Ingres.

5.2.5 Setting Ingres Environment Variables Once the files have been copied into place, use “ingsetenv” to change any default values for the following variables:  II_DATABASE  II_CHECKPOINT  II_JOURNAL  II_DUMP  II_WORK  II_NUM_OF_PROCESSORS  II_TIMEZONE_NAME  II_TEMPORARY See the Advantage Ingres Command Reference Guide for the syntax of the ingsetenv

5.2.6 Embedded Ingres specific environment variables In addition to the above there is an embedded specific variable used to control the post install configuration process.  II_EMBED_INSTALL When set to ‘ON’ Ingres will configure itself without asking further questions.

5.2.7 Setting up the Embedded Ingres Products Setup scripts for Ingres products are located in the $II_SYSTEM/ingres/utility directory. These scripts should be invoked in batch mode using the –batch flag as there is no requirement for user interaction Setup scripts should only be executed for the products that are to be install The following is a complete list of available scripts:

iisuabf Sets up Ingres ABF iisulib Sets up the Ingres library (required) Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

iisudbms Sets up Ingres DBMS iisuice Sets up Ingres ICE iisuc2 Sets up Ingres C2 Security iisunet Sets up Ingres NET iisustar Sets up Ingres STAR iisutm Sets up Ingres Terminal Monitor iisutux Sets up Ingres DTP for Tuxedo iisubr Sets up the Ingres Protocol Bridge iisues Sets up Ingres Enhanced Security iisurep Sets up Ingres Replicator iisujdbc Sets up the Ingres JDBC Server.

Appendix B contains a sample UNIX setup script that has been used by the AHD group to set up Ingres on Solaris

6. Embedded Ingres API for Windows NT/2000/XP/.NET

The following API functions have been provided to assist in the installation and configuration of Embedded Ingres. Applications using this API should include the file tngapi.h which is located in the %II_SYSTEM%\ingres\files directory and should be linked with the %II_SYSTEM%\ingres\lib\oiutil.lib import library.

6.1 II_GetEnvVariable Get the value of an Ingres environment variable.

6.1.1 Synopsis #include VOID II_GetEnvVariable(char *name, char **value)

6.1.2 Description Given an Ingres environment variable name, get the corresponding value from the current environment or the Ingres symbol.tbl, depending upon where it is set first. The current environment takes precedence.

6.1.3 Parameters

Parameter Type Description name Input The name of the Ingres environment variable value Output If successful, the value of the named resource, otherwise NULL. It must be the address of a char pointer to a block of memory that has already been allocated; the function will not allocate memory for “value”.

6.1.4 Return Value N/A

6.2 II_GetIngresInstallSize Report the size needed for an Ingres install.

6.2.1 Synopsis #include VOID II_GetIngresInstallSize(char *ResponseFile, double *InstallSize)

6.2.2 Description Given the full path to a response file, report the size needed for an Ingres install. It is +-2MB accurate.

6.2.3 Parameters

Parameter Type Description ResponseFile Input The full path to a response file to use. InstallSize Output If successful, the size needed for the Ingres install in MB, otherwise -1.

6.2.4 Return Value N/A

6.3 II_GetResource Get the value of a specified configuration parameter.

6.3.1 Synopsis #include int II_GetResource(char *ResName, char *ResValue)

6.3.2 Description Given an Ingres configuration parameter, this function checks the config.dat file for the corresponding value

6.3.3 Parameters

Parameter Type Description ResName Input The name of the configuration resource ResValue Output If successful, the value of the named resource

6.3.4 Return Value If successful - OK

6.4 II_GetVersion Get the version of Ingres installed on a machine as well as II_SYSTEM. This API function actually lives in iigetver.dll, which is installed when Embedded Ingres is installed.

6.4.1 Synopsis #include int II_GetVersion(II_VERSIONINFO *VersionInfo)

6.4.2 Description This function grabs the version of Ingres installed as described in the config.dat file, as well as the value of II_SYSTEM. This information is returned via the II_VERSIONINFO structure, defined as: struct _II_VERSIONINFO { char szII_SYSTEM[MAX_STRING_LEN]; char szII_VERSIONSTRING[MAX_STRING_LEN]; };

6.4.3 Parameters

Parameter Type Description VersionInfo Output An II_VERSIONINFO variable, to contain the version of Ingres installed and the value of II_SYSTEM

6.4.4 Return Values

II_OK Successful II_ERROR_INVALID_PARAMETER_PASSED A proper II_VERSIONINFO variable was not passed. II_ERROR_CANNOT_FIND_II_SYSTEM The value of II_SYSTEM cannot be retrieved. II_ERROR_CANNOT_OPEN_CONFIG_DAT The config.dat file cannot be opened. II_ERROR_CANNOT_FIND_VERSION_STRING A proper version string cannot be retrieved from the

config.dat file. II_ERROR_II_SYSTEM_DIR_NOT_EXIST The II_SYSTEM directory does not exist.

6.5 II_GCNapi_ModifyNode Add or delete a virtual node.

6.5.1 Synopsis #include int II_GCNapi_ModifyNode( int opcode, int entryType, char *virtualNode, char *netAddress, char *protocol, char *listenAddress, char *username, char *password)

6.5.2 Description This function adds or deletes virtual nodes. Virtual nodes can then be used to access remote databases from an Embedded Ingres instance.

6.5.3 Parameters

Parameter Type Description opcode Input The type of operation. Valid values are ADD_NODE (for adding a virtual node) and DELETE_NODE (for deleting a virtual node). entryType Input The type of virtual node. Valid values are 1 (for a public virtual node) and 2 (for a private virtual node). virtualNode Input The name of the virtual node. It can be concatenated with the database name (i.e., vnode::database). netAddress Input Remote machine address. This can be either a hostname or a numeric address. protocol Input Transport protocol of the virtual node. Valid values are “wintcp” (TCP/IP), “lanman” (LANMAN), “nvlspx” (SPX/IPX), and “decent” (DECnet). listenAddress Input Listen address of the remote Communications server (GCC). The first two characters of the listen address will be the installation id of the remote instance; the remaining characters will be a numeric number (i.e., “II1”). When a GCC is started, its listen address is printed to the console as well as the errlog.log.

username Input User id used to connect to the remote instance. password Input Password of the user id. This password is encrypted before it is passed to the Ingres internal virtual node creation function.

6.5.4 Return Value If successful, the return value is 0. If unsuccessful, an Ingres specific error number (such as 0xC0021 (“server unavailable”)) is returned.

6.6 II_GCNapi_Node_Exists Does a particular virtual node exist?

6.6.1 Synopsis #include BOOL II_GCNapi_Node_Exists(char *vnode)

6.6.2 Description Given a virtual node name, this function will test to see if it exists. This function will not test to see if the virtual node is valid. This function will only work with globally defined virtual nodes.

6.6.3 Parameters

Parameter Type Description vnode Input The name of the virtual node.

6.6.4 Return Value TRUE if it exists and FALSE if it does not exist.

6.7 II_GCNapi_TestNode Tests a given virtual node.

6.7.1 Synopsis #include int II_GCNapi_TestNode(char *vnode)

6.7.2 Description Given a virtual node name, this function will test the remote Name server connection through the virtual node.

6.7.3 Parameters

Parameter Type Description vnode Input The name of the virtual node.

6.7.4 Return Value If successful, the return value is 0. If unsuccessful, an Ingres specific error number (such as 0xC0021 (“server unavailable”)) is returned.

6.8 II_IngresServiceName Get the internal name of the Ingres service.

6.8.1 Synopsis #include VOID II_IngresServiceName(char *ServiceName)

6.8.2 Description This function grabs the internal Ingres service name. This will be of the form Ingres_Database_, where ‘’ is the Ingres installation identifier.

6.8.3 Parameters

Parameter Type Description ServiceName Output The internal name of the Ingres service

6.8.4 Return Values N/A

6.9 II_IngresVersion Get the latest Ingres version installed on a machine.

6.9.1 Synopsis #include int II_IngresVersion(VOID)

6.9.2 Description This function, only available on Windows NT/2000/XP/.NET, reports the latest version of Ingres installed on a machine.

6.9.3 Parameters N/A

6.9.4 Return Values

Valid Ingres versions are returned from the function as positive integer values defined in the tngapi.h file. A negative value indicates that an error has been encountered attempting to retrieve the Ingres version. II_INGRES_1200 CA-OpenIngres 1.2/00 II_INGRES_1201 CA-OpenIngres 1.2/01 II_INGRES_209712 OpenIngres 2.0/9712 II_INGRES_209808 Ingres II 2.0/9808 II_INGRES_209905 Ingres II 2.0/9905 II_INGRES_200001 Ingres II 2.0/0001 II_INGRES_250006 Ingres II 2.5/0006 II_INGRES_250011 Ingres II 2.5/0011 II_INGRES_260106 Advantage Ingres 2.6/0106 II_INGRES_260201 Advantage Ingres 2.6/0201 II_INGRES_260207 Advantage Ingres 2.6/0207 II_INGRES_260305 Advantage Ingres 2.6/0305 II_INGRES_NOT_FOUND Ingres not installed on the machine II_CONFIG_NOT_FOUND Unable to locate the config.dat file II_CONFIG_BAD_PARAM Version information not found in config.dat or an error occurred accessing config.dat

6.10 II_IngresVersionEx Get the latest Ingres version installed on a machine.

6.10.1 Synopsis #include int II_IngresVersionEx(char *VersionString)

6.10.2 Description This function, only available on Windows NT/2000/XP/.NET, reports the latest version of Ingres installed on a machine. The VersionString parameter is optional, and can be substituted for with NULL.

6.10.3 Parameters

Parameter Type Description VersionString Output The version of Ingres in a string representation (i.e., ii260201intw3200)

6.10.4 Return Values

Valid Ingres versions are returned from the function as positive integer values defined in the tngapi.h file. A negative value indicates that an error has been encountered attempting to retrieve the Ingres version.

II_INGRES_1200 CA-OpenIngres 1.2/00 II_INGRES_1201 CA-OpenIngres 1.2/01 II_INGRES_209712 OpenIngres 2.0/9712 II_INGRES_209808 Ingres II 2.0/9808 II_INGRES_209905 Ingres II 2.0/9905 II_INGRES_200001 Ingres II 2.0/0001 II_INGRES_250006 Ingres II 2.5/0006 II_INGRES_250011 Ingres II 2.5/0011 II_INGRES_260106 Advantage Ingres 2.6/0106 II_INGRES_260201 Advantage Ingres 2.6/0201 II_INGRES_260207 Advantage Ingres 2.6/0207 II_INGRES_260305 Advantage Ingres 2.6/0305 Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

II_INGRES_NOT_FOUND Ingres not installed on the machine II_CONFIG_NOT_FOUND Unable to locate the config.dat file II_CONFIG_BAD_PARAM Version information not found in config.dat or an error occurred accessing config.dat

6.11 II_PingGCN Determine if the Name Server for this particular Ingres installation is running

6.11.1 Synopsis #include BOOL II_PingGCN(VOID)

6.11.2 Description An Ingres Name Server ‘bed check’ is issued to determine if the Ingres Name Server is running/responding to requests. Since a Name Server must be running for an Ingres installation to function, this is a good test to determine if this particular Ingres installation is available

6.11.3 Parameters N/A.

6.11.4 Return Values If the Name Server responds to the request – TRUE else FALSE

6.12 II_PrecheckInstallation Validate the Ingres installation environment prior to starting the actual installation process.

6.12.1 Synopsis #include int II_PrecheckInstallation(char *response_file, char *error_msg)

6.12.2 Description This function checks a given machine environment to verify that it will support the current release of Advantage Ingres. The following checks are made:  A minimum operating system version (for example, on Windows, this is NT 4.0 Service Pack 3).  Other required software (currently none).  Check the install path o Check that it exists. o Check that the user can write to it (to create a directory). o Check that the path does not include any disallowed characters (currently, only numeric, alphabetic – including accented alphabetic such as é, and underscore characters are allowed).  Check that the hostname does not contain any disallowed characters. For a list of allowed characters please refer to Appendix F.  Check that the username does not contain any disallowed characters. For a list of allowed characters please refer to Appendix F. In order to achieve the hostname and username checks, a new parameter must now be added to the Ingres response file. This parameter, “charmap”, must be set equal to the full path and file name of a character description file that will be used with the pre- check function. The latest one is supplied here:

inst1252.chx

Keep in mind that this is a binary file. Any changes which need to be made should be directed toward Ingres development. In order to execute a program which utilizes this function PRIOR to an instance of Ingres being installed, the following DLLs must be placed in the directory containing the program: OICLFDATA.DLL, OICLFNT.DLL, OIGCFDATA.DLL, OIGCFNT.DLL, OIGCNDATA.DLL, OIGCNNT.DLL, OIGLFDATA.DLL, OIGLFNT.DLL, OIUTIL.DLL. Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

6.12.3 Parameters

response_file Input Full path to the Embedded Ingres response file, e.g., “C:\Program Files\CA\Ingres\ingres.rsp”. error_msg Output Sufficiently large buffer to a possible error message. The maximum length of an error message is defined by MAX_IIERR_LEN. Error messages are truncated to the MAX_IIERR_LEN prior to return.

6.12.4 Return Values

II_SUCCESSFUL No problems or errors II_NULL_PARAM Bad (null) parameter II_NO_INSTALL_PATH II_SYSTEM not in response file (or response file does not exist) II_OS_NOT_MIN_VERSION Operating system version below that required II_BAD_PATH The installation path cannot be parsed or does not exist II_PATH_NOT_DIR The installation path is not a directory II_PATH_CANNOT_WRITE The current user cannot write to the installation path II_INVAL_CHARS_IN_PATH The installation path contains disallowed characters. II_NO_CHAR_MAP “charmap” not found in response file or file does not exist. II_CHARMAP_ERROR An error has occurred processing the char map file. II_GET_COMPUTER FAIL The call to return computer name failed. The system error message is returned. II_GET_HOST_FAIL The call to return host name failed. The system error message is returned. II_GET_USER_FAIL The call to return the user name failed. The system error message is returned. II_UNMATCHED_NAME The computer name and the host name are different. II_INVALID_HOST The computer name contains disallowed characters.

II_INVALID_USER The user name contains disallowed characters.

6.13 II_ServiceStarted Has this Ingres installation been started as a service?

6.13.1 Synopsis #include BOOL II_ServiceStarted(VOID)

6.13.2 Description This function is only available on Windows NT/2000/XP/.NET. The function queries the service manager to determine if the Ingres service for this particular Ingres installation is running Advantage Ingres 2.6 provides support for multiple Ingres installations on a single NT machine. To accomplish this, an installation identifier has been appended to the end of the service name (e.g. Ingres_Database_WV). Use of the Embedded Ingres API will shield users from any future service name changes.

6.13.4 Return Values If the Ingres service identified by the value of II_INSTALLATION is running – TRUE else FALSE

6.14 II_StartService Start the Ingres Service associated with this particular installation

6.14.1 Synopsis #include int II_StartService(VOID)

6.14.2 Description This function is only available on Windows NT/2000/XP/.NET, instructs the service manager to start the service associated with this particular Ingres installation. Advantage Ingres 2.6, provides support for multiple Ingres installations on a single NT machine and the installation identifier has been appended to the end of the service name (e.g. Ingres_Database_WV). Use of the Embedded Ingres API will shield users from any future service name changes.

6.14.4 Return Values If the service fails to start - Non-zero The extended error information returned after a failed call to the Win32 API StartService() is returned to the calling function If the service started successfully – OK

6.15 II_StartServiceSync Start the Ingres Service associated with this particular installation, and do not return until success or failure.

6.15.1 Synopsis #include int II_StartServiceSync(VOID)

6.15.2 Description This function is only available on Windows NT/2000/XP/.NET, instructs the service manager to start the service associated with this particular Ingres installation. It will NOT return until the service is either started or failed to start. Advantage Ingres 2.6, provides support for multiple Ingres installations on a single NT machine and the installation identifier has been appended to the end of the service name (e.g. Ingres_Database_WV). Use of the Embedded Ingres API will shield users from any future service name changes.

6.15.4 Return Values If the service fails to start - Non-zero The extended error information returned after a failed call to the Win32 API StartService() is returned to the calling function If the service started successfully – OK

6.16 II_StopService Stop the Ingres Service associated with this particular installation.

6.16.1 Synopsis #include int II_StopService(VOID)

6.16.2 Description This function is only available on Windows NT/2000/XP/.NET, instructs the service manager to stop the service associated with this particular Ingres installation Advantage Ingres 2.6, provides support for multiple Ingres installations on a single NT machine and the installation identifier has been appended to the end of the service name (e.g. Ingres_Database_WV). Use of the Embedded Ingres API will shield users from any future service name changes

6.16.4 Return Values If the service fails to stop – Non-zero The extended error information returned after a failed call to the Win32 API ControlService() is returned to the calling function. If the service was stopped successfully – OK

6.17 II_TNG_Version Is this an Embedded Ingres installation?

6.17.1 Synopsis #include BOOL II_TNG_Version(VOID)

6.17.2 Description Checks the config.dat file for the ii.*.setup.embed_installation parameter. If found and set to “ON”, reports that to the Embedded Ingres application

6.17.4 Return Values If this installation has been configured as an Embedded Ingres installation – TRUE else FALSE

7. Ingres Configuration System

7.1 Introduction Ingres configuration parameters are stored in the config.dat file located in the Ingres files directory A set of rules defines the permissible values for configuration parameters as well as defining the relationships between various parameters. These rules are stored in the Configuration Rules System (CRS) files that exist in the same directory. A CRS file has been added for the ‘Embedded Ingres’ parameters, this file is called tng.crs and can be modified to ensure that configuration parameters are set at installation time Some Ingres Configuration parameters are derived from others so it is not advisable to edit the config.dat file; Changes should be made through CBF, the Configuration Manager, or the iisetres utility

7.2 Generating the configuration file The config.dat file may be regenerated by issuing the command: iigenres %COMPUTERNAME% tng.rfm in the %II_SYSTEM%\ingres\files directory

7.3 Setting a Configuration Parameter from the Command Line The iisetres utility may be used to set the value of a configuration parameter and to recalculate any derived parameters For further information on the iisetres utility, refer to the Advantage Ingres Command Reference Guide

7.4 Getting the value of a Configuration Parameter from the Command Line The iigetres utility may be used to get the value of a configuration parameter from the command line For further information on the iigetres utility, refer to the Advantage Ingres Command Reference Guide

Appendix A. Sample Response File

; Ingres Response File Created By Ingres Installation ; Wizard On: Sunday, January 7, 2001 at 06:17:25 PM.

[Ingres Configuration] Ingres DBMS Server=”TRUE” Ingres/Net=”TRUE” Ingres/Star=”FALSE” Ingres Embedded SQL/C=”TRUE” Ingres Embedded SQL/COBOL=”FALSE” Ingres Querying and Reporting Tools=”FALSE” Ingres/Vision=”FALSE” Ingres/Replicator=”FALSE” Ingres/ICE=”FALSE” OpenROAD Development=”FALSE” OpenROAD Runtime=”FALSE” Ingres Online Documentation=”TRUE” Ingres Visual DBA="TRUE" JDBC Driver="TRUE" JDBC Server="TRUE" hidewindows=”TRUE” leaveingresrunninginstallincomplete=”TRUE” ingresprestartuprunprg=”D:\prestart.exe” ingresprestartuprunparams=”-u 300 -l 45” destroytxlogfile=”FALSE” upgradeuserdatabases=”FALSE” removeoldfiles=”TRUE” language=”ENGLISH” timezone=”NA-EASTERN” terminal=”IBMPC” installationcode=”EM” charset=”IBMPC850” logfilesize=”32” serviceauto=”TRUE” servicepassword=”” enableTCPIP=”TRUE” enableNETBIOS=”FALSE” enableSPX=”FALSE” enableDECNET=”FALSE” enablesql92=”FALSE” primarylogdir=”E:\Ingres25”

of 70 2018年5月4日 Computer Associates —CONFIDENTIAL Embedded Ingres User Guide enableduallogging=”FALSE” duallogdir=”E:\Ingres25” iidatabasedir=”E:\Ingres25” iicheckpointdir=”E:\Ingres25” iijournaldir=”E:\Ingres25” iidumpdir=”E:\Ingres25” iiworkdir=”E:\Ingres25” II_SYSTEM=”E:\Ingres25”

Appendix B. Sample UNIX Setup Script

#!/bin/sh # # (C) 1995 Computer Associates International, Inc # # Copyright (C) 1991 - 1993 NetWorx, Incorporated. All Rights Reserved. # # Copyright (C) 1994 Legent Software, Inc., as an # unpublished work. This notice does not imply unrestricted or public # access to these materials which are a trade secret of Legent # Corporation or its subsidiaries or affiliates (together referred to # as "LEGENT"), and which may not be reproduced, used, sold or # transferred to any third party without LEGENT's prior written consent. # # All Rights Reserved # # RESTRICTED RIGHTS LEGEND # Use, duplication, or disclosure by the Government is subject to # restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in # Technical Data and Computer Software clause at DFARS 252.227-7013. # # Author: OpenIngres development group. # Created: Sept 27, 1999 #

### fast install program ## ## 18-apr-95 (hanch04) ## created. ## 05-oct-98 (hanch04)

## Modified to be generic for TNG ## 08-Aug-03 (karye01) ## Replaced “uname –n” with iipmhost to correct problem with domain names such ## as “usilhost.ca.com”.

# ingbatch.sh II_DISTRIBUTION PRODUCTS IS_UPGRADE II_INSTALLATION II_TIMEZONE_NAME LOG_BYTES PASSWORD

# ingbatch.sh /cdrom/ingres.tar NO "tm,dbms,net,ome" WV NA-EASTERN 49152 netpass

# $II_SYSTEM must be set. # $II_SYSTEM/ingres/bin and $II_SYSTEM/ingres/utility must be in $PATH # $II_SYSTEM/ingres/lib must be in $LD_LIBRARY_PATH or equivalent

# II_DISTRIBUTION would be like /cdrom/ingres.tar # IS_UPGRADE YES or NO - is this an upgrade # PRODUCTS for TNG base would be "tm,dbms,net,ome" # II_INSTALLATION is our installation ID (Currently WV) # II_TIMEZONE_NAME for the east coast NA-EASTERN # LOG_BYTES in megabytes for log file size # PASSWORD is the installation password we create in netutil

# Exit values # 0 Success # 1-10+ Fail

# Make sure we have enough parameters [ -z "$7" ] && { # All parameters must be passed # echo "Usage: ingbatch.sh II_DISTRIBUTION IS_UPGRADE PRODUCTS Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

II_INSTALLATION II_TIMEZONE_NAME LOG_BYTES PASSWORD" exit 1 }

# Verify we have an II_SYSTEM [ -z "$II_SYSTEM" ] && { # echo "II_SYSTEM is not set." exit 2 }

# cd to where we want to extract our files to cd $II_SYSTEM/ingres

#Pull out our parameters and needed variables II_DISTRIBUTION=$1 IS_UPGRADE=$2 PRODUCTS=$3 II_INSTALLATION=$4 TIME_ZONE=$5 LOG_KBYTES=$6 PASSWORD=$7

#export needed items export II_DISTRIBUTION export II_INSTALLATION export LOG_KBYTES

# Extract the install directory tar xpf $II_DISTRIBUTION install

# default embed_user to ON

embed_user=ON

# if we are upgrade, check to see if we are already using embed_user or tng_user if [ "$IS_UPGRADE" = "YES" ] then CONFIG_HOST=`iipmhost` val1=`$II_SYSTEM/ingres/utility/iigetres ii.$CONFIG_HOST.setup.embed_user` val2=`$II_SYSTEM/ingres/utility/iigetres ii.$CONFIG_HOST.setup.tng_user`

[ "$val1" = "OFF" -o "$val1" = "off" ] && embed_user=OFF [ "$val2" = "OFF" -o "$val2" = "off" ] && embed_user=OFF [ "$val1" = "" -a "$val2" = "" ] && embed_user=OFF fi

# Setup for embed Ingres (as per Ingres Development) II_MANIFEST_DIR=$II_SYSTEM/ingres/install II_EMBED_INSTALL=ON II_EMBED_USER=$embed_user export II_MANIFEST_DIR; export II_EMBED_INSTALL export II_EMBED_USER

# per Ingres - we should delete all files in bin and utility directories prior to upgrade [ -d $II_SYSTEM/ingres/bin ] && rm -f $II_SYSTEM/ingres/bin/* [ -d $II_SYSTEM/ingres/utility ] && rm -f $II_SYSTEM/ingres/utility/*

# Pull the files off the distribution without running setup install/ingbuild -nosetup -install=$PRODUCTS $II_DISTRIBUTION > /dev/null

# Set our default timezone ingsetenv II_TIMEZONE_NAME $TIME_ZONE

# Don't run with dual logs if not using multiple devices. II_DUAL_LOG="" export II_DUAL_LOG echo "Configuring the system database (this may take a while)"

# Run setup in batch mode utility/iisudbms -batch >/dev/null || exit 5 utility/iisunet -batch >/dev/null || exit 6 utility/iisutm >/dev/null || exit 7

# If not upgrade, set CONFIG_HOST variable if [ “$IS_UPGRADE” = “NO” ] then CONFIG_HOST=`iipmhost` fi

# if we are upgrade, then upgrade db and exit if [ "$IS_UPGRADE" = "YES" ] then # Make sure embed_user is set the way we want it (must be before ingstart) $II_SYSTEM/ingres/utility/iisetres ii.$CONFIG_HOST.setup.embed_user $embed_user

# start Ingres, but make sure rmcmd is down ingstart > /dev/null 2>&1 ingstop -rmcmd > /dev/null 2>&1

# do the upgrade for all databases, or you will not be able to access them upgradedb -all >> $II_SYSTEM/ingres/files/upgradedb.log 2>&1 # restart rmcmd ingstart -rmcmd > /dev/null 2>&1

exit 0 fi

# Default log file size may be too small # Change the size of the transaction log

. iisysdep csinstall rcpstat -online && exit 11 # Check version 2.5 and above have no II_LOG_FILE and # II_LOG_FILE_NAME in the symbol table if [ "$ING_VERS" = "2.0" -o "$ING_VERS" = "" ]; then II_LOG_FILE=ìngprenv II_LOG_FILE` II_LOG_FILE_NAME=ìngprenv II_LOG_FILE_NAME` rm $II_LOG_FILE/ingres/log/$II_LOG_FILE_NAME else PART_NO=ìigetres ii.${LOCALHOSTNAME}.rcp.log.log_file_parts` while [ $PART_NO -gt 0 ] do II_LOG_FILE=ìigetres ii.${LOCALHOSTNAME}.rcp.log.log_file_$PART_NO` II_LOG_FILE_NAME=ìigetres ii.${LOCALHOSTNAME}.rcp.log.log_file_name` rm $II_LOG_FILE/ingres/log/$II_LOG_FILE_NAME.l* PART_NO=èxpr $PART_NO - 1` done fi iisetres ii.${LOCALHOSTNAME}.rcp.file.kbytes $LOG_KBYTES ipcclean iimklog csinstall rcpconfig -force_init_log -silent ipcclean

# Start Ingres to run netutil ingstart >/dev/null 2>&1 || { ingstop >/dev/null 2>&1 exit 8

# Create an installation password

VERSION=`$II_SYSTEM/ingres/install/ingbuild -version=net` RELEASE_ID=`echo $VERSION | sed "s/[ ().\/]//g"` stty echo if netutil -file- << ! C G login $CONFIG_HOST * $PASSWORD ! then iisetres ii.$CONFIG_HOST.setup.passwd.$RELEASE_ID on else #Unable to create installation password due to "netutil" failure. iisetres ii.$CONFIG_HOST.setup.passwd.$RELEASE_ID off exit 10 fi

# Stop Ingres since we started it ingstop > /dev/null 2>&1 exit 0

Appendix C. Frequently Asked Questions

When should I use OpenAPI? Never, it is recommended that the Microsoft ODBC API is used instead. The performance of the ODBC API is comparable with that of the OpenAPI but it is significantly easier to use and there are examples of how to use on the web

How do I report a problem with Embedded Ingres? If you encounter what you believe to be a bug, log an issue in StarTrak in the Ingres ISL S 1 queue. Notify [email protected] when the issue is opened so that he may give it his immediate attention Emails and voice mails to specific individuals are not result in the issue being logged. All problems must be logged before they will be progressed

How do I create an Ingres image containing only those files that I need to ship with my product on Windows NT/2000/XP/.NET? Use the makeimg utility, which is documented in Chapter 2 of this User Guide

How do I generate a template response file? Invoke the installer with the /c flag: install /c

When upgrading from OpenIngres 1.2, a number of DLL’s are left behind in the utility directory and can cause problems. How do I get rid of them? Ingres on NT, was originally built for NT 3.5 and during the installation it is necessary to start Ingres to create iidbdb, the DLL's in the bin directory were not being found in the path by ingstart which is located in the utility directory The easiest way to resolve this issue, without having to reboot the machine partway through the Ingres installation, was to put a copy of the DLL's in the utility directory. With the release of NT 3.51 this issue was resolved and when support for NT 3.5 was dropped, we stopped putting a copy of the DLL's in the utility directory. The upgrade procedure that is documented in the release notes states: 5. Remove all files from the %II_SYSTEM%\ingres\utility, %II_SYSTEM%\ingres\vdba and %II_SYSTEM%\ingres\bin directories A response file option removeoldfiles, which deletes these files automatically, is outlined in Chapter 3

Should I enable journaling on my databases?

It is recommended that any databases that contain critical information that would need to be recovered following a failure be setup with journaling enabled

Should I perform regular checkpoints on my databases? It is recommended that any databases that contain critical information that would need to be recovered due to a failure be checkpointed on a regular basis This should be done by the application itself, or within the documentation informing the end user that checkpointing is an important part of maintaining the system Checkpointing can be done without bringing down the Ingres system by performing an online checkpoint For more information about online checkpoint’s refer to the Advantage Ingres System Reference Guide and the DBA Guide.

Should my application be responsible for starting and stopping Ingres? That decision should be taken by the application developer

How can I design my table schema to make Ingres work best for my application? See Appendix E - Simplified Relational Database Design

How should I maintain Ingres from my application’s point of view? It is crucial that Ingres is not treated as a ‘Black Box’. It should be noted that this product is referred to as ‘Embedded’ Ingres and not ‘Black Box’ Ingres. This has been done intentionally because thought needs to be given into maintaining the data schema and Ingres. All products require maintenance. Maintenance of Ingres should be provided as part of the applications maintenance programs. If there are no maintenance procedures for Ingres provided with the application, then end users should be made aware of the maintenance that needs to be applied to Ingres, and should be told either how it should be done or where advice on Ingres maintenance can be found.

Appendix D. Advantage Ingres 2.6 New Features

DBMS New Features

Row Producing Procedures This enhancement to the database procedure language of Ingres addresses a long-standing shortcoming in its capabilities; namely, the ability to read and return to the caller multiple rows from a select statement. One of the great values of server executed database procedures is that the program logic of the procedure is executed entirely in the server address space. Multiple SQL DML requests are all executed in a single invocation of the procedure, with only one interaction with the client application. The ability to process and return multiple “rows” of some composite data type with a single call to a server-resident database procedure adds further to the potential for improved performance of an application. In a typical computing environment with applications executing on a variety of computers throughout a network, this approach can significantly reduce the footprint of the client application and the traffic across the network.

Raw Location Support Earlier releases of Ingres supported the use of raw partitions for logging. In Ingres 2.6 support has been added for raw data locations on UNIX platforms. Raw data locations should provide noticeable performance improvements over cooked locations.

Increased Maximum Size of Character Data-Types In releases prior to Ingres 2.6, character data-types were limited to a maximum size of 2000 bytes; this restriction was imposed when the maximum size of a row was limited 2K. This limit has been increased to a maximum of 32,000 bytes where the page size supports it.

Concurrent Rollback In releases prior to Ingres 2.6 rollback was limited to a single transaction (thread) at a time. Ingres 2.6 permits the concurrent recovery of multiple transactions.

Hash Aggregation A change to the Ingres 2.6 aggregate handling routines make it more competitive with other DBMS products, and allow Ingres to better support data-mining products such as CA’s DecisionBase, which make extensive use of data aggregation.

Composite Histograms Ingres has long had difficulty in estimating the selectivity of where clauses with

restriction predicates on several columns in the same table. This is largely because of a simplistic assumption that individual column values are independent of one another. This enhancement allows for the creation of composite or multi-column histograms. They model much more accurately the dependence of the values of one column on another and lead to far better selectivity estimates, and ultimately to better query plans.

Hash Join Support A hash join is one in which a hash table is built with the rows of one of the join sources by hashing on the key column(s) of the join. The rows of the other join source are then read and hashed into the table on their key column(s). The hashing of the second set of rows should quickly identify pairs of joining rows. The advantage of this technique is that it requires no index structures on the join column(s), nor does it require sorting on the join column(s).

Usermod Utility One of our goals in moving forward is to automate database maintenance as much as possible, to this end we have added a utility, usermod, which allows users to run the modify commands on user tables. Just like sysmod, which performs a ‘modify’ on system catalogs, this is a useful utility for maintaining user tables. Running this utility on regular basis or when the table has excess overflow pages, will improve performance of user applications. For further information on the Usermod utility please refer to the Command Reference Guide.

Copydb Enhancements Following a number of user requests, the copydb utility has been modified to include several options and flags which will modify the copy.in and copy.out scripts based on users requirements. For example, the user will now be able to specify the order in which the copy and modify statements are written to the copy.in script, i.e. whether to copy the data into the tables and then run a modify statement or vice versa. Other examples include the ability to remove hard-coded paths to the copy scripts, exclusion of location names, exclusion of user specific permissions e.g. grant statements etc. For further information on the copydb enhancements please refer to the Command Reference Guide.

XML Import/Export Utility XML is as a cross-platform, software and hardware independent tool for transmitting information. XML is largely perceived as the future standard for data exchange and clients have long requested support for XML in Ingres. As a starting point we have added a utility, which is able to export and import XML data from Ingres tables to/ from XML files. For further information on the XML import/export utility please refer to the Command Reference Guide.

Alternative Template File for CPIO Database Checkpoints (UNIX only) There is a new ckpdb/rollforwarddb template file included with Ingres 2.6, which enables

the use of cpio as an alternative to tar to checkpoint/rollforward databases. To use this alternate template file, you must set the environment variable II_CKTMPL_FILE to point to this template by issuing the command: ingsetenv II_CKTMPL_FILE $II_SYSTEM/ingres/files/cktmpl_cpio.def

Context Sensitivity of Reserved Words The Ingres 2.6 parsers treat reserved words in a context sensitive manner so they only cause errors when used in an ambiguous context. In the past, new releases of Ingres that introduced additional reserved words would inevitably result in syntax errors in applications written long before that use one of the reserved words as an entity name (table, column, etc.).

ODBC Driver Enhancements

ODBC Support on UNIX Ingres 2.6 includes an ODBC driver on certain UNIX platforms; please refer to the Appendix for details for your platform.

ODBC 3.5 Support Ingres 2.6 includes an ODBC 3.5 level driver for both Windows and UNIX platforms.

Microsoft Transaction Server Support Ingres 2.6 and the Ingres 2.6 ODBC Driver provide support for Microsoft Transaction Server.

JDBC Enhancements The following JDBC 2.0 extensions have been implemented: Compatibility with existing JDBC releases Driver allows execution in JDK 1.1 environment. Batch processing javax - two-phase commit javax - client connection pooling Updateable result-sets

ICE Enhancements

ICE Development Environment Ingres ICE 2.6 provides support for integrated XML development environments such as XMetaL (http://www.xmetal.com/top_frame.sq) Please see the ICE User Guide for further information.

DBA Tool Enhancements

Ingres Journal Analyzer The Ingres Journal Analyzer (IJA) is a powerful graphical tool, which provides an interface to the Ingres journal files. Amongst other things, the Ingres Journal Analyzer can you used to recover data from the journals and to apply journaled transactions to other databases, both local and remote. For a complete description of IJA please refer to the Ingres System Administrator’s Guide.

Ingres Import Assistant The Ingres Import Assistant is a wizard that greatly simplifies the task of importing data from a standard file format to an Ingres database. For more information please refer to the Ingres System Administrator’s Guide.

RMCMD Enhancements In releases prior to Ingres 2.6, users commonly encountered problems running utilities that require exclusive access to the iidbdb database because rmcmd keeps a session open on this database. To counter this problem in Ingres 2.6, rmcmd attaches to imadb instead of iidbdb. imadb is a system database that contains no historical data so it is rarely if ever backed up and requires little or no maintenance.

Appendix E. Simplified Relational Database Design

This paper describes some of the hallmarks of a relational database. The relational model is fundamentally simple; however, like all simple concepts it is often prey to over-simplification, particularly with regard to designing a working database. Therefore, this paper not only presents the basic structure of a relational database but also offers some design principles that ensure a trouble-free relational installation.

In a relational database, data appear as a collection of tables. A table is a rectangular array composed of rows (records) and columns (fields). The only restrictions that apply to any table are the following:

 Each row must have the same form.  Rows must not have duplicates (i.e., no two rows can have identical values in all fields).

The process of simplifying your data structures (i.e., tables) to these restrictions is called normalization. Normalization offers the following benefits:

 The representation of data is the simplest to understand and utilise.  Normalized records are compatible with all file access methods and database management system types. In other words, normalization can fit into your present system.  Normalized record definition is unaffected by changes to the storage structures of tables in a relational database, allowing greater flexibility in database design.  Normalization allows the use of a complete relational command vocabulary to define the manipulation of the data in the structured design phase as well as in the actual operation of the database.  Normalization provides an optimal place to start the physical design process of the database. The designer becomes aware of all compromises and adjustments made to maintain normalized records in the physical implementation of the database.

The process of normalization starts with ensuring that records are in first normal form (1NF). A row (record) is in 1NF if it contains no repeating groups of data. If records contain repeating groups, the repeat groups must be removed and stored as new records. These new records must carry the minimum number of additional data elements (i.e., columns or fields) required to form a key that is unique for each group occurrence.

Example 1, 1NF:

Before

------(repeating groups) ------ Supplier Part Quantity Part Quantity J1 P1 100 P2 200 S6 P2 50 L3 P2 300 P3 100

The rows are revised to have the same form by repeating the supplier number, thus eliminating the repeating groups:

Supplier Part Quantity J1 P1 100 J1 P2 200 S6 P2 50 L3 P2 300 L3 P3 100

The tables constitute what the user sees and do not necessarily indicate how the data are represented in storage. Thus any apparent redundancy that 1NF may entail need not require additional storage space. Moreover, the so-called redundancy (e.g., “J1” appears in both the first and second rows) is not redundant, because the records in which similar data appears are not replicates of each other. Each row is unique.

Because very few physical restrictions are placed on how data can be organised into tables, it is possible to design a relational database with problems on update operations. Using the previous 1NF table as an example, data about the parts’ colours and the suppliers’ cities are added:

Example 2, Further Normalization:

Before (i.e., the data are combined):

Supplier S_city Part Colour Quantity J1 NY P1 Red 100 J1 NY P2 White 200 S6 LA P2 White 50 L3 DC P2 White 300 L3 DC P3 Blue 100

Although all the rows are of the same form and each row is unique, such a choice of data in a Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

of 70 2018年5月4日 Computer Associates —CONFIDENTIAL Embedded Ingres User Guide table creates the following problems on updates:

 Replacement anomaly: To change a single data item may require change in more that one place. For example, changing JI’s city from NY to SF requires changing data in two locations.  Insertion anomaly: To insert a new supplier who as yet furnishes no part requires leaving several columns (fields) blank.  Deletion anomaly: if S6 stops supplying P2, you cannot delete P2 without removing S6 from the database.

To prevent these update anomalies requires further normalization. This further normalization is a decomposition process resulting in tables that contain data concerning only one semantic object. The question of what a semantic object is, is discussed below. The fundamental result of this decomposition is that the table in Example 2 is broke down so that the data are in their simplest form.

A record is said to be in second normal form (2NF) if the record is initially 1NF and if every non-key data element (i.e., column or field) in the record is fully dependent on the primary key. The primary key element is that element embodying the main idea of the table. If an element x is a key element in some other record, remove it from the table and create a new record type, if necessary. This usually requires that you create a new table. If an element x is not a key element in some other record, determine the key element(s) upon which x is dependent and add x to those records. Form new record types, if necessary.

A record is said to be in third normal form (3NF) if the record is already in 2NF.

 If there is only one key element that embodies the main idea of the table  If every non-key data element is fully dependent on the entire primary key  If no non-key element is dependent on any other non-key element

If there are any multiple dependencies among non-key elements of a record, remove those non- key elements and, following the rules for 2NF, relocate the elements or form additional records, if necessary. The difference between 2NF and 3NF is that 2NF allows for a “hierarchy” of dependence among non-key elements. Records in 2NF can have one key element, some “first level” non-key elements dependent on the key, and other non-key elements that depend on the “first-level” non-key elements. Such multiple dependencies in 2NF are disallowed in 3NF.

Following this procedure, the prior table of combined data above is converted to the following tables:

After:

Supplier Table:

Supplier S_city J1 NY Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

S6 LA L3 DC

Part Table:

Part Colour P1 Red P2 White P3 White

On-order Table:

Supplier Part Quantity J1 P1 100 J1 P2 200 S6 P2 50 L3 P2 300 L3 P3 100

The net effect of these rules of normalization is that the tables are simpler to understand and less subject to update anomalies.

These standard rules of normalization can simplify data structures, but another useful process for solving these problems employs a semantic model. A semantic model involves considering data in terms of the atomic objects (i.e., objects that cannot be broken down) that the data serve to describe. These objects are called entities, and typical examples include people, organisational units and goods. The next step of the procedure is to group entities into types so that entities of the same type are described by similar data. For examples “employer” might be an entity type, and “supplier” another.

Two descriptors are used in conjunction with entities. The first descriptor is attribute, which is an assignment of a unique pair (attribute name, attribute-value) to an entity. For example, you can assign an attribute such as (birthyear, 1940) to an entity of the “employee” type. The value can be a number, a character string or even another entity. If an attribute is defined on any entities of a given type, then the attribute is defined on all entities of that type. For instance, if the entity type “employee” is assigned an attribute for birthyear, then any instance of an employee also has a birthyear associated with it. This restriction gives an operational meaning to the assertion above that entities of the same type are similar, because they are described by similar data.

The second descriptor for entities is relationship. This is a many-to-many correspondence among entities of two or more types. For example, “supply” might constitute a relationship among entities of types “supplier,” “part” and “assembly”. A single instance of the relationship Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

of 70 2018年5月4日 Computer Associates —CONFIDENTIAL Embedded Ingres User Guide consists of one entity from each of the participating types, such as the following:

supplier J1 < --- > part P2 < --- > assembly x 7

A relationship, then, can be viewed as a collection of elements, each collection being a concatenation (or tuple) of entities. An attribute can be defined on a relationship as an assignment of a unique value (e.g., quantity supplied) to each instance of the relationship.

The previous discussion of semantics suggests that a clear procedure exists for designing a relational database free from update anomalies. This procedure is the following:

 Introduce a permanent (i.e., not updatable) identifier that serves as a template or model for any individual entity  Ensure that each table in the database contains all the information concerning either a single entity type or a single relationship, but not both

This procedure further answers the question posed earlier of what a semantic object is. A semantic object is either an entity type or a relationship, since an entity type or a relationship can constitute the main idea or key element of a table. Accordingly, the simple rule for designing a trouble-free relational database is:

ONE AND ONLY ONE SEMANTIC OBJECT PER TABLE

That basic rule is the essence of normalization.

Example 3, The Simple Rule:

Given three entity types,

 Employee  Department  Job

The attributes (with examples including attribute-name and attribute-value) for each entity can be summarized as follows:

Entity Type Attribute Employee Emp_id (empno,236) [identifier] Emp_name (ename, “Jones”) Birthyear (byr,1940) Current_job_id (jno,24) Complete DO NOT COPY—DESTROY IF UNAUTHORIZED

Department Dept_id (dno,15) [identifier] Dept_name (dname, “EDP”) Location (area, “Room 26”) Manager (mgr, “Filstrup”) Job Job_id (jno,24) [identifier] Job_title (jtitle, “Programmer”) Salary (salary, 22000)

Suppose that there are two relationships specified as follows:

Relationship Participating Entity Type Attribute Assignment Employee Percent_time Department Qualified Employee Yrs_experience Job

Application of the simplified design procedure produces the following database description:

Table Name(s) Column Name(s) Employee Empno, ename, byr, jno Department Dno, dname, area, empno (manager) Job Jno, jtitle, salary Assignment Empno, dno, percent_time Qualified Empno, jno, yrs_experience

Presto! You have just created a trouble-free database

Appendix F. Map of Supported Characters

This section outlines the various supported characters in Embedded Ingres. The key to this character map is as follows: p character can be in a path s character can start a username and be in a username n character can be in a username but cannot start a username o combined with s and n, character can be in a hostname a a path control character cannot appear in a pathname (i.e., directory / filename)

charmap.txt