belden e., greenberg j., slattery h. - oracle call interface getting started (part no. a90166-01)...

8/7/2019 Belden E., Greenberg J., Slattery H. - Oracle Call Interface Getting Started (Part No. A90166-01) (Release 9.0.1) (2001)

1/30

Oracle Call Interface

Getting Started

Release 9.0.1 for Windows

June 2001

Part No. A90166-01


2/30

Oracle Call Interface Gettiing Started, Release 9.0.1 for Wind ows

Part No. A90166-01

Copyr ight 1995, 2001, Oracle Corpora tion. All rights reserv ed.

Contr ibuto rs: Eric Belden , Janis Greenb erg, Helen Slattery, Ravi Thamm aiah, and Bob Thom e.

The Programs (which include both the software and d ocumentation) contain proprietary information of

Oracle Corporation; they are p rovided u nder a license agreement containing restrictions on use an d

disclosure and are also protected by copyright, patent, and oth er intellectual and ind ustrial property

laws. Reverse engineering, disassembly, or decomp ilation of the Program s is prohibited .

The information contained in this docum ent is subject to change w ithout notice. If you find any p roblemsin the docum entation, please report them to us in wr iting. Oracle Corporation d oes not warran t that this

documen t is error free. Except as m ay be expressly permitted in your license agreement for these

Programs, no part of these Programs may be reprodu ced or transmitted in any form or by any m eans,

electronic or mechanical, for any p urp ose, without the express written p ermission of Oracle Corporation.

If the Programs are d elivered to th e U.S. Government or an yone licensing or u sing the program s on

behalf of the U.S. Governm ent, the following n otice is ap plicable:

Restricted Rights N otice Programs delivered subject to the DOD FAR Supplement are "commercial

compu ter software" and u se, du plication, and disclosure of the Programs, including d ocumentation,

shall be subject to the licensing restrictions set forth in the ap plicable Oracle license agreem ent.Otherwise, Programs d elivered subject to the Federal Acquisition Regulations are "restricted compu ter

software" and u se, dup lication, and disclosure of the Program s shall be subject to the restrictions in FAR

52.227-19, Commercial Com pu ter Software - Restricted Rights (Jun e, 1987). Oracle Corp oration , 500

Oracle Park wa y, Redw ood City, CA 94065.

The Programs are n ot intend ed for u se in any nuclear, aviation, mass transit, medical, or other inherently

dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,

redu ndan cy, and other m easures to ensure the safe use of such app lications if the Programs are u sed for

such pu rposes, and Oracle Corporation d isclaims liability for any d amages caused by such u se of the

Programs.

Oracle is a registered trad emark, and Oracle9i and PL/ SQL are trademarks or registered trademarks of

Oracle Corporation. Other names may be tradem arks of their respective owners.


3/30

iii

Contents

Send Us Your Comments .................................................................................................................... v

Preface........................................................................................................................................................... vii

Au dience ................................................................................................................................................ viii

Or ganiza tion .......................................................................................................................................... viiiRelated Documentation ....................................................................................................................... viii

Conventions............................................................................................................................................ ix

Documentation Accessibility ............................................................................................................. xiv

Whats New in Oracle Call Interface?......................................................................................... xv

Oracle9i Release 1 (9.0.1) New Featu res in Oracle Call Interface ................................................. xviOracle8i Release 1 (8.1.5) New Featu res in Oracle Call Interface ................................................. xvi

OCI Release 7.x Functions .................................................................................................................. xvi

1 Introduction to Oracle Call Interface

What is the Oracle Call Interface? ................................................................................................... 1-2

What is Included in the OCI Package? ........................................................................................... 1-2

Oracle Directory Structure ................................................................................................................ 1-2

Sample Programs ............................................................................................................................... . 1-3

2 Building OCI Applications

Writing OCI Applications ................................................................................................................. 2-2

Compiling OCI Applications ........................................................................................................... 2-2
http://comments_template.pdf/http://comments_template.pdf/


4/30

iv

Linking OCI Applications ................................................................................................................ 2-3

oci.lib............................................................................................................................................... 2-3Client DLL Loading When Using LoadLibrary()..................................................................... 2-4

Running OCI Applications ............................................................................................................... 2-4

The Oracle XA Library ....................................................................................................................... 2-4

Compiling and Linking an OCI Program with the Oracle XA Library ................................ 2-5

Using XA Dynamic Regis trat ion ................................................................................................ 2-5

Ad ding an Environmental Variable for the Cu rrent Session .......................................... 2-6

Ad ding a Registry Variable for All Session s ..................................................................... 2-6

XA and TP Mon itor Inform ation ................................................................................................ 2-7

Using the Object Type Translator and the INTYPE File Assistant ............................................ 2-7

Index


5/30

v

Send Us Your Comments

Oracle Call Interface Gettiing Started, Release 9.0.1 for Windows

Part No. A90166-01

Oracle Corporation w elcomes your comments and su ggestions on the quality and u sefulness of this

docum ent. Your inp ut is an imp ortant p art of the information used for revision.

s Did you find any errors?

s Is the information clearly p resented?

s Do you n eed m ore information? If so, where?

s Are the examples correct? Do you need more examp les?

s What features did you like most?

If you find any errors or have any other suggestions for improvement, please indicate the documen t

title and p art num ber, and the chap ter, section, and page number (if available). You can sendcomments to us in the following w ays:

s E-mail: ntd [email protected]

s FAX - (650) 506-7365 Attn : Oracle Database for Wind ows Documenta tion

s Postal service:

Oracle Corporation

Oracle Database for Wind ows Docum entation Manager

500 Oracle Parkw ay, Mailstop 1op6

Redw ood Shores, CA 94065

USA

If you w ould like a reply, please give your name, add ress, telephone nu mber, and (optionally)

electronic mail ad dress.

If you have p roblems with the software, please contact your local Oracle Sup port Services. Contact

information for Oracle Sup por t Services is available at this Web site:

http://www.oracle.com/support/


6/30

vi


7/30

vii

Preface

This guide p rovides introd uctory information for the Oracle Call Interface (OCI)

run ning on Microsoft Wind ows N T, Windows 95/ 98, and Wind ows 2000.

This preface contains these topics:

s Audience

s Organization

s Related Docum entation

s Conventions

s Documentation Accessibility


8/30

viii

AudienceOracle Call Interface Getting Started for Window s is intended for developers w ho

create applications written in C tha t interact with one or m ore Oracle Servers.

To use this docum ent, you need to know :

s How to compile and link a C program.

s Your Microsoft Window s operating system.

OrganizationThis docum ent contains:

Chapter 1, "Introduction to Oracle Call Interface"

Provides introductory information to help you get started w ith the OCI.

Chapter 2, "Building OCI Applications"Provides an overview of how to bu ild Oracle da tabase app lications using OCI.

Related DocumentationFor more information, see these Oracle resources:

s Oracle9i Database installation gu ide for Wind ows

s Oracle9i Database release notes for Wind ows

s Oracle9i Database Administrators Guide for Windows

s Oracle Enterprise Manager Administrators Guide

s Oracle9i Net Services Administrators Guide

s Oracle9i Real A pplication Clusters Concepts

s Oracle9i Database New Features

s Oracle9i Database Concepts

s Oracle9i Database Reference

s Oracle9i Database Error Messages

s Oracle Call Interface Programmers Guide

In North Am erica, printed docum entation is available for sale in the Oracle Store at


9/30

ix

http://oraclestore.oracle.com/

Custom ers in Europe, the Mid dle East, and Africa (EMEA) can p urchase

documentation from

http://www.oraclebookshop.com/

Other custom ers can contact their Oracle representative to pu rchase printed

documentation.

To down load free release notes, installation d ocumenta tion, white p apers, or other

collateral, please visit the Oracle Technology Network (OTN). You m ust reg ister

online before using OTN; registration is free and can be don e at

http://technet.oracle.com/membership/index.htm

If you already have a u sername and password for OTN, then you can go directly to

the d ocumentation section of the OTN Web site at

http://technet.oracle.com/docs/index.htm

ConventionsThis section d escribes the conventions used in the text and code examples of this

docum entation set. It describes:

s Convention s in Text

s Conventions in Code Examples

s Conventions for Window s Operating Systems

Conventions in Text

We use various conventions in text to help you more qu ickly identify special terms.

The following table describes those conventions an d p rovides examples of their use.

Convention Meaning Example

Bold Bold typ eface indicates terms th at aredefined in the text or terms that app ear ina glossary, or both.

When you specify this clause, you create anindex-organized table.


10/30

x

Conventions in Code Examples

Code examples illustrate SQL, PL/ SQL, SQL*Plus, or oth er comm and -line

statements. They are displayed in a mon ospace (fixed-width ) font and separated

from n ormal text as shown in th is example:

SELECT username FROM dba_users WHERE username = MIGRATE;

The following table describes typograp hic conventions u sed in code examp les and

provides examp les of their use.

Italics Italic typeface indicates book titles oremphasis.

Oracle9i Database Concepts

Ensure that th e recovery catalog and targetdatabase do notreside on the same d isk.

UPPERCASE

monospace

(fixed-width

font)

Upp ercase mon ospace typeface indicateselements sup plied by the system. Suchelements include parameters, privileges,datatypes, RMAN keywords, SQLkeywords, SQL*Plus or u tility command s,packages and m ethods, as well assystem-supp lied column names, databaseobjects and structu res, usernames, androles.

You can specify th is clause only for a NUMBERcolumn.

You can back up the data base by using theBACKUP command.

Query the TABLE_NAME colum n in the USER_TABLES data dictionary view.

Use the DBMS_STATS.GENERATE_STATSprocedure.

lowercase

monospace

(fixed-width

font)

Lowercase monospace typeface ind icatesexecutab les, filenam es, directory names,and sample user-supplied elements. Suchelements include comp uter and database

nam es, net service names, and connectidentifiers, as well as user-supp lieddatabase objects and structures, colum nnam es, packages and classes, usernamesand roles, program un its, and param etervalues.

Note: Some programmatic elements use amixture of UPPERCASE and lowercase.Enter these elements as shown.

Enter sqlplus to open SQL*Plus.

The password is specified in the orapwd file.

Back up the d atafiles and control files in the

/disk1/oracle/dbs directory.

The department_id, department_name,and location_id colum ns are in thehr.departments table.

Set the QUERY_REWRITE_ENABLEDinitialization parameter to true.

Connect as oe user.

The JRepUtil class implements thesemethods.

lowercase

monospace

(fixed-width

font) italic

Lowercase monospace italic fontrepresents placeholders or variables.

You can specify th eparallel_clause.

Run Uold_release.SQL where old_releaserefers to the release you installedprior to up grading.



11/30

xi


[ ] Brackets enclose one or more optionalitems. Do not enter the brackets.

DECIMAL (digits [ ,precision ])

{ } Braces enclose two or m ore items, one ofwh ich is required. Do not enter the braces.

{ENABLE | DISABLE}

| A vertical bar represents a choice of twoor more opt ions within brackets or braces.Enter one of the options. Do not enter the

vertical bar.

{ENABLE | DISABLE}

[COMPRESS | NOCOMPRESS]

... Hor izontal ellipsis points ind icate either:

s That we have omitted p arts of thecode that are not directly related tothe example

s That you can repeat a portion of thecode

CREATE TABLE ... AS subquery;

SELECT col1, col2, ... , coln FROM

employees;

.

.

.

Vertical ellipsis points indicate that w ehave om itted several lines of code notd irectly related to the examp le.

Other notation You must enter symbols other thanbrackets, braces, vertical bars, and ellipsispoints as shown.

acctbal NUMBER(11,2);

acct CONSTANT NUMBER(4) := 3;

Italics Italicized text ind icates placeholders orvariables for wh ich you mu st supp ly

particular values.

CONNECT SYSTEM/system_password

DB_NAME = database_name

UPPERCASE Upp ercase typeface indicates elementssup plied by the system. We show theseterms in u pp ercase in ord er to distinguishthem from terms you define. Unless termsapp ear in brackets, enter them in theorder and with the spelling shown.How ever, because these terms are notcase sensitive, you can enter th em in

lowercase.

SELECT last_name, employee_id FROM

employees;

SELECT * FROM USER_TABLES;

DROP TABLE hr.employees;

lowercase Lowercase typeface ind icatesprogramm atic elements that you supp ly.For example, lowercase ind icates nam esof tables, columns, or files.

Note: Some programmatic elements use amixture of UPPERCASE and lowercase.Enter these elements as show n.

SELECT last_name, employee_id FROM

employees;

sqlplus hr/hr

CREATE USER mjones IDENTIFIED BY ty3MU9;


12/30

xii

Conventions for Windows Operating Systems

The following table d escribes conventions for Window s operating systems andprovides examp les of their use.


Choose Start > How to start a program. For example, tostart Oracle Database ConfigurationAssistant, you mu st click the Start buttonon the taskbar and then choose Programs

> Oracle -HOME_NAME> DatabaseAdministration > Database ConfigurationAssistant.

Choose Start > Program s > Oracle -HOME_NAME> Database Administration > DatabaseConfiguration Assistant

C:\> Represents the Windows comm andpromp t of the current hard disk drive.Your prom pt reflects the subd irectory inwh ich you are working. Referred to as thecomm and p romp t in this guide.

C:\oracle\oradata>

HOME_NAME Represents the Oracle home name.

The home name can be u p to 16alphan um eric characters. The only specialcharacter allowed in the hom e name is theunderscore.

C:\> net start OracleHOME_NAMETNSListener


13/30

xiii

ORACLE_HOMEand ORACLE_BASE

In releases prior to 8.1, when you

installed Oracle comp onents, all

subdirectories were located u nder a top

level ORACLE_HOMEdirectory that by

default was:

s C:\orant for Windows N T

s C:\orawin95 for Wind ows 95

s

C:\orawin98 for Wind ows 98or w hatever you called you r Oracle home.

In this O ptim al Flexible Architecture

(OFA)-complian t release, all

subdirectories are not u nd er a top level

ORACLE_HOMEdirectory. There is a top

level directory called ORACLE_BASEthat

by defau lt is C:\oracle. If you install

release 9.0 on a comp uter w ith no otherOracle software installed, the d efault

setting for the first Oracle home d irectory

is C:\oracle\ora90. The Oracle hom e

directory is located d irectly under

ORACLE_BASE.

All directory path examples in this guide

follow OFA conven tions.

See Oracle9i Database Gett ing Started forWindows for additional information on

OFA compliances and for information on

installing Oracle products in non-OFA

compliant directories.

Go to the ORACLE_BASE\ORACLE_HOME\rdbms\admin directory.



14/30

xiv

Documentation AccessibilityOracles goal is to make ou r prod ucts, services, and sup porting docum entation

accessible to the d isabled community with good usability. To that end , our

docum entation includ es features that m ake information available to users of

assistive technology. This documentation is available in HTML format, and contains

markup to facilitate access by the disabled comm unity. Stand ards will continu e to

evolve over time, and Oracle is actively engaged w ith other ma rket-leading

technology vendors to ad dress technical obstacles so that our docum entation can be

accessible to all of ou r custom ers. For ad ditional information, visit the Oracle

Accessibility Program Web site at

http://www.oracle.com/accessibility/

JAWS, a Window s screen read er, may not always correctly read the code examples

in this docum ent. The conventions for writing code require that closing braces

should app ear on an otherwise emp ty line; how ever, JAWS may n ot always read a

line of text tha t consists solely of a bracket or brace.


15/30


16/30


17/30

Introduction to Oracle Call Interface 1-1

1Introduction to Oracle Call Interface

This chapter p rovides introdu ctory information to help you get started w ith Oracle

Call Interface (OCI) for Wind ows.

This chap ter contains these top ics:

s What is the Oracle Call Interface?

s What is Includ ed in the OCI Package?

s Oracle Directory Structure

s Sample Programs

See Also: For detailed information abou t OCI, includ ing new

features an d function descriptions, see the Oracle Call Interface

Programmers Guide.


18/30

What is the Oracle Call Interface?

1-2 Oracle Call Interface Gettiing Started

What is the Oracle Call Interface?The Oracle Call Interface (OCI) is an app lication program ming interface (API) that

allows app lications wr itten in C to interact with one or m ore Oracle Servers. OCI

gives your program s the capability to perform the full range of database operations

that a re possible with Oracle9i database, including SQL statement p rocessing and

object manip ulation.

What is Included in the OCI Package?The Oracle Call Interface for Window s package includ es:

s Oracle Call Interface

s Required Sup port Files (RSFs)

s Oracle Universal Installer

s Header files for comp iling OCI app lications

s Library files for linking OCI applications

s Sample programs for demonstrating how to build OCI applications

The OCI for Wind ows p ackage includ es the add itional libraries required for linking

your O CI programs on Window s NT, Window s 2000, and Wind ows 95/ 98.

Oracle Directory StructureWhen you install the Oracle Call Interface for Window s, Oracle Un iversal Installer

creates an ORACLE_BASE\ORACLE_HOMEd irectory on the hard d rive of your

compu ter. The d efault Oracle home d irectory is C:\oracle\ora90.

The OCI files are located in the ORACLE_BASE\ORACLE_HOMEdirectory, as are the

library files needed to link an d run OCI app lications, and link with oth er Oracle for

Wind ows N T produ cts, such as Oracle Forms.

The ORACLE_BASE\ORACLE_HOMEdirectory contains the following directories thatare relevant to OCI:

Directory Name Contents

\bin Executable and help files

\oci Oracle Call Interface d irectory for Window s files


19/30

Sample Programs

Introduction to Oracle Call Interface 1-3

Sample ProgramsWhen OCI is installed, a set of samp le program s and their corresponding project

files are copied to the ORACLE_BASE\ORACLE_HOME\oci\samples subdirectory.

Oracle Corporation recommend s that you bu ild an d run these samp le programs to

verify tha t OCI has been successfully installed and to familiarize yourself with the

steps involved in d eveloping OCI app lications.

To bu ild a sample, run a batch file(make.bat)at the comm and p rompt. For

example, to build the cdemo1.c samp le, enter the following comm and :

C:> make cdemo1

After you finish using th ese sample p rograms, you can d elete them if you choose.

A sample OCI application specific to Windows p latforms is included. cdemomt.c

dem onstrates OCI multithread ing wh ich is the thread safety feature of Oracle9i is

also included on the Window s platforms. This samp le program requ ires the emp

table from the default database. The program spaw ns tw o simultaneous threads

that attem pt to insert different emp loyee nam es with the same ID numbers. Threadsynchronization is demonstrated.

ociucb.c should be compiled u sing ociucb.bat. This batch file creates a DLL

and places it in the ORACLE_BASE\ORACLE_HOME\bin directory. To load user

callback fun ctions, set the environmen t/ registry variable ORA_OCI_UCBPKG =

OCIUCB.

\oci\include Head er files, such as oci.h and ociap.h

\oci\samples Samp le programs

\precomp\admin\ottcfg.cfg Object Type Translator utility and defau ltconfiguration file

See Also: For more information on m ultithread ing, see the OracleCall Interface Programmers Guide.

Directory Name Contents


20/30

Sample Programs



21/30

Building OCI Applications 2-1

2Building OCI Applications

This chapter p rovides an overview of how to bu ild Oracle database app lications

using OCI.

This chap ter contains these topics:

s Writing OCI App lications

s Comp iling OCI App lications

s Linking OCI App lications

s The Oracle XA Library

s Using th e Object Type Translator an d the INTYPE File Assistant

See Also: See the Oracle Call Interface Programmers Guide for

detailed information abou t writing OCI app lications.


22/30

Writing OCI Applications


Writing OCI ApplicationsThe general goal of an OCI app lication is to connect to an Oracle Server, engage insome sort of data exchange, and p erform necessary d ata p rocessing. While some

flexibility exists in the order in which specific tasks can be performed, every OCI

app lication must accomplish particular steps.

The basic program ming structure u sed by th e OCI is as follows:

1. Initialize the OCI program ming env ironment an d p rocesses.

2. Allocate necessary hand les, and establish a server connection and a usersession.

3. Issue SQL statements to th e server, and perform n ecessary app lication d ata

processing.

4. Free statements and hand les not to be reused or reexecute p repared statem ents

again, or prepare a new statement.

5. Terminate user session an d server connection.

Compiling OCI ApplicationsWhen you compile an OCI app lication, you m ust include the approp riate OCI

head er files. The h eader files are located in the \ORACLE_BASE\ORACLE_

HOME\oci\include directory.

For examp le, if you are u sing Microsoft Visual C++ 6.0, you wou ld need to pu t in

the ap prop riate path in the Directories page of the Op tions dialog in the Tools

menu. See Figure 21, "Directories Tab of the Op tions Dialog".

Note: The initialization of an O CI environm ent in Shared Data

Mode that is discussed in the Oracle Call Interface Programmers

Guide is not sup ported on Windows.


23/30

Linking OCI Applications


Figure 21 Directories Tab of the Options Dialog

Linking OCI Applications

The OCI calls are imp lemented in d ynam ic link libraries (DLLs) that Oracleprovid es. The DLLs are located in the ORACLE_BASE\ORACLE_HOME\bin

directory and are part of the Required Sup port Files (RSFs).

To u se the Oracle DLLs to make OCI calls, you can either d ynam ically load the DLL

and function entry points, or you can link your ap plication with the import library

oci.lib. Oracle Corporation on ly provides the oci.lib imp ort library for use

with the Microsoft Comp iler. Other comp ilers, though likely comp atible with the

Oracle DLLs, are not tested and sup ported by Oracle for use w ith OCI.

When using oci.lib with the Microsoft Compiler, you d o not have to indicate any

special link op tions.

oci.liboci.lib is a single, programmatic interface to Oracle. Oracle has removed any

version nu mber from the library nam e.

See Also: See your compilers docum entation for sp ecific

information about comp iling you r app lication and special compiler

options.

R i OCI A li ti


24/30

Running OCI Applications


Client DLL Loading When Using LoadLibrary()

The following d irectories are searched in this order by LoadLibrary:

s Directory from w hich the ap plication is loaded

s Current directory

s Wind ows N T or Wind ows 2000:

s 32-bit Window s system directory (system32). Use the

GetWindowsDirectory function to obtain the p ath of this directory.

s 16-bit Windows directory (system). There is no Win32 function tha t

obtains the p ath of th is directory, but it is searched .

s Wind ows 95 or Wind ows 98:

s Wind ows directory. Use the GetWindowsDirectory function to obtain

the p ath of this directory.

s Directories that are listed in the PATH env ironment variable

Running OCI ApplicationsTo ru n an OCI app lication, ensure th at the entire correspond ing set of RSFs is

installed on the compu ter that is running your OCI app lication.

The Oracle XA LibraryThe XA Ap plication Program Interface (API) is typically used to enable an Oracle9idatabase to interact w ith a transaction processing (TP) monitor, such as:

s BEA Tuxedo

s IBM Tran sarc Encina

s IBM CICS

You can also use TP mon itor statements in your client p rograms. The use of the XAAPI is supp orted from OCI.

The Oracle XA Library is automatically installed as part of Oracle9 i Enterprise

Edition. The following components are created in your Oracle home d irectory:

The Oracle XA Library


25/30



Compiling and Linking an OCI Program with the Oracle XA Library

To compile and link an OCI program:

1. Compile program.c by u sing Microsoft Visual C++, making sure to includ e

ORACLE_BASE\ORACLE_HOME\rdbms\xa in your path.

2. Linkprogram.obj w ith the following libraries:

3. Run program.exe.

Using XA Dynamic RegistrationThe Oracle9i da tabase supp orts the use of XA dynam ic registration. XA dynam ic

registration improves the p erformance of applications interfacing w ith

XA-comp liant TP mon itors. For TP Monitors to use XA dyn amic registration w ith

an Oracle database on Wind ows N T, you m ust ad d either an environm ental variable

or a registry variable to the Window s NT comp uter on w hich your TP monitor is

running. See either of the following sections for instructions:

s Add ing an Environmenta l Variable for the Curren t Session

s Adding a Registry Variable for All Sessions

Component Location

oraxa9.lib ORACLE_BASE\ORACLE_HOME\rdbms\xa

xa.h ORACLE_BASE\ORACLE_HOME\rdbms\demo

Library Located in...

oraxa9.lib ORACLE_BASE\ORACLE_HOME\rdbms\xa

oci.lib ORACLE_BASE\ORACLE_HOME\oci\lib\msvc



26/30



Adding an Environmental Variable for the Current Session

Add ing an environmental variable at the comman d promp t affects only the currentsession.

To add an environmental variable:

From th e compu ter where your TP mon itor is installed, enter the following a t the

command prompt:

C:\> set ORA_XA_REG_DLL = vendor.dll

where vendor.dll is the TP mon itor DLL provid ed by you r vend or.

Adding a Registry Variable for All Sessions

Add ing a registry variable affects all sessions on you r Window s NT comp uter. This

is useful for comp uters w here only one TP monitor is runn ing.

To add a registry variable:

1. Go to the comp uter w here your TP monitor is installed.

2. On Window s NT or Wind ows 2000, enter the following at the comm and

prompt:

C:\> regedt32

On Windows 95/ 98, enter:

C:\> regedit

The Registry Editor window appears.

3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID.

4. Choose the Add Value option in the Edit menu . The Ad d Value d ialog box

appears.

5. Enter ORA_XA_REG_DLL in the Value N ame text box.

6. Select REG_EXPAND_SZ from the Data Type list box.

7. Choose OK. The String Editor dialog box appears.

8. Type vendor.dll in the String field, wh ere vendor.dll is the TP monitor

DLL provid ed by your vendor.

Using the Object Type Translator and the INTYPE File Assistant


27/30



9. Choose OK. The Registry Editor add s the param eter.

10. Choose Exit from the Registry menu .

The registry exits.

XA and TP Monitor InformationRefer to the following general information abou t XA and TP monitors:

s Distributed TP: The XA Specification (C193) published by the Op en Group .

See the Web site at

s http://www.opengroup.org/publications/catalog/tp.htm

s The Open Group., 1010 El Camino Real, Suite 380, Menlo Park, CA 94025,

U.S.A.

s Your specific TP monitor d ocum entation

Using the Object Type Translator and the INTYPE File AssistantThe Object Type Translator (OTT) is used to create C-struct rep resentations of

Abstract Data Types that h ave been created and stored in an Oracle9i database.To take ad vantage of objects run OTT against the d atabase, and a head er file is

generated that includ es the C structs. For examp le, if a PERSON type has been

created in the database, OTT can generate a C struct with elements correspond ing to

the attr ibutes of PERSON . In ad dition, a nu ll ind icator stru ct is created that

represents nu ll information for an instance of the C struct.

The INTYPE file tells the OTT which object typ es shou ld be tr anslated . This file also

controls the nam ing of the generated structs. The INTYPE File Assistant is a w izardthat helps d evelopers to create the INTYPE file.

Note that the CASE specification inside the INTYPE files, such as CASE=LOWER,

app lies only to C identifiers that are not sp ecifically listed, either through a TYPE or

TRANSLATE statement in the INTYPE file. It is importan t to provide the type name

with the ap prop riate cases, such as TYPE Person and Type PeRsOn, in the INTYPE

file.

See Also: For more information abou t the Oracle XA Library and

using XA d ynam ic registration, see Oracle9i Application Developers

Guide - Fundamentals.



28/30

g j yp


The INTYPE File Assistan t genera tes type nam es in the INTYPE file with th e same

case as in th e database. By d efault, all of the typ es in the d atabase are created in

up per case.

In order to p reserve the case, use double quotes when creating types in the

database. For examp le:

CREATE TYPE "PeRsOn" AS OBJECT...

Object type dep endencies are not checked by th e Oracle INTYPE File Assistant.

When adding an object typ e for inclusion in the IN TYPE file, the IN TYPE File

Assistant d oes not add other object types with dependency relationships.

The INTYPE File Assistant requ ires explicit tran slations for object typ es or attr ibutes

wh ose nam es contain non-ASCII characters. These object types or attributes are

indicated by the p redefined tag Identifier in the fields wh ere the translations would

be entered. Users are required to override this tag w ith the C identifier translation

for the correspond ing object type or attr ibute. The INTYPE File Assistant does n ot

create the INTYPE file until all required translations have been entered .

OTT on Window s NT can be invoked from th e comman d line. Add itionally, a

configuration file may be named on the comm and line. For Window s NT, the

configuration file is ottcfg.cfg, located in ORACLE_BASE\ORACLE_

HOME\precomp\admin.

Additional Information: See the Oracle Call Interface Programmers

Guide for more information about OTT and IN TYPE files. In

add ition, see the on line help for OTT.


29/30

Index-1

Index

B

bin di rectory, 1-2

Borland support, xvi

building OCI applications, 2-1

C

cdemomt.c, 1-3compiling

OCI applications, 2-2

OCI with Oracle XA, 2-5

Oracle XA Library, 2-4

configuration files, 1-3

locat ion , 1-3

Ddemonstration programs, 1-3

directory structures, 1-2

dynamic registration


E

EMP tab le, 1-3

F

features

new, xv

G

generic documentation references

compiling and linking OCI applications, 2-2, 2-3

demonstration programs, 1-3

invoking OTT from the command line, 2-8

OTT configuration file, 2-8

thread safety, 1-3

XA linking file names

Hhead er files

location of, 1-3, 2-2

I

include directory, 1-3

INTYPE File Assistant, 2-7

L

libraries

oci.lib , 2-3

linking

OCI applications, 2-3

OCI with Oracle XA, 2-5


LoadLibrary , 2-4

M

make.ba t, 1-3

mult ithreading, 1-3


30/30

Index-2

O

Object Type Translator (OTT), 2-7OCI

building applications, 2-1

new features, new features, xv


overview, 1-2

release 7.x functions, xvi

sample programs, 1-3

OCI app lications

compiling, 2-2lin kin g, 2-3

ru nn in g, 2-4

w ritin g, 2-2

oci directory, 1-2

oci.d ll, xv i

oci.lib , xvi, 2-3

ociw32.dll, xvi

ociw32.lib, xvi

Oracle Call Interface. See OCI

Oracle XA Library

additional documentation, 2-7

compiling and linking an OCI program, 2-5

dynamic registration, 2-5

funct ions, 2-4

overview, 2-4

Oracle9i database

transaction processing monitor, 2-4OTT (Object Type Translator), 2-7

ottcfg.cfg, 1-3

R

registry

REGEDT32, 2-6

required support files, 1-2

RSFs, 1-2running OCI applications, 2-4

S

sample programs, 1-3

samples directory, 1-3

shared data mode, 2-2

T

transaction processing monitoradditional documentation, 2-7

interacting with Oracle9i database, 2-4

types, 2-4

W

writing OCI applications, 2-2

XXA. See Oracle XA Library

belden e., greenberg j., slattery h. - oracle call interface getting started (part no. a90166-01)...

Documents