Oracle Call Interface --- DATATYPES, BINDING AND DEFINING


Datové typy

Pohovoříme o externích datových typech uživaných v aplikacích OCI. Při té příležitosti pohovoříme trochu o datových typech Oraclu.

Datové typy Oraclu

Jednou z hlavních funkcí OCI programu je komunikovat s databází přes Oraclovský server. Aplikace OCI mohou vracet data z databáze pomocí SQL SELECT dotazů, nebo modifikovat existující data v tabulkách pomocí INSERT, UPDATE, DELETE.

Oracle reprezentuje data částečně ve vnitřním formátu. Například NUMBER, CHAR, DATE. OCI aplikace však nepracují s vnitřní datovou reprezentací dat. OCI aplikace pracují s datovým typem hostitelského jazyka, které jsou předdefinovány v jazyce, v němž jsou napsány. Když jsou data přenášena mezi OCI klientskou aplikací a databázovou tabulkou, knihovny OCI konvertují data mezi vnitřními datovými typy a vnějšími.

Externí datové typy jsou definovány v OCI hlavičkových souborech. Když OCI aplikace váže vstupní proměnnou, jeden z vázaných parametrů je indikace externího datového typu kódu proměnné. Podobně výstupní proměnné jsou specifikovány v definovaném volání, externí reprezentace požadovaných dat musí být specifikována.

V některých případech jsou externí datové typy podobné interním. OCI je schopné a provádí širokou škálu konverzí datových typů, když jsou přenášena data mezi Oracle a OCI aplikací. Je více OCI externích datových typů než vnitřních typů Oraclu. V některých případech je jednoduchý externí typ mapován na interní typ, v jiných případech jsou několikanásobné externí typy mapovány na jednoduchý interní typ.

Př. SELECT sal FROM emp WHERE empno=:employee_number

a chcete, aby se vrátil plat jako řetězec spíše než jako binární floating point format, specifikujete Oracle externí řetězcový typ dat, např. VARCHAR2 nebo CHAR pro parametr v OCIDefineByPos() volání pro volání sloupce sal.

Pokud chcete tuto informaci vrátit jako binární floating-point, specifikujete externí datový typ FLOAT.

K řízení datových konverzí je nutné použít kód s vhodnými externími datovými typy v souvisejících define-rutinách. Je nutné říci Oraclu, kde jsou vstupní a výstupní proměnné ve vašem OCI programu a jejich datové typy a délka.

Kód interních datových typů

V některých případech potřebují aplikace OCI znát vnitřní reprezentaci dat Oraclu. Například často potřebujete znát datový typ sloupce dynamického SQL dotazu kvůli definici vstupních proměnných k přijetí čtených dat. Po spuštění dotazu, můžete použít kombinaci OCIParamGet() a OCIAttrGet() funkcí k obdržení popsané informace. Můžete získat tytéž informace z popsané obsluhy bez spuštění příkazu voláním OCIDescribeAny() a poté kombinací OCIParamGet() a OCIAttrGet().

Kód externích datových typů

Externí kód datových typů udává Oraclu, jak je hostitelská proměnná reprezentována ve vašem programu. To určuje, jak jsou data konvertována, když jsou vrácena s výstupními proměnnými ve vašem programu, nebo jak jsou konvertována ze vstupních proměnných do hodnot sloupců v Oraclu. Např. pokud chcete konvertovat NUMBER ve sloupci Oraclu na variabilní řetězec, specifikujete VARCHAR2 externí typ datového kódu v ORCIDefineByPos() volání, které definuje výstupní proměnné.

Ke konverzi vázané proměnné na proměnnou ve sloupci Oraclu, specifikujete kód externího datového typu, který koresponduje s typem vázané proměnné. Např. pokud chcete vstup řetězce jako 02-FEB-65 do sloupce DATE, specifikujete datový typ jako řetězec a nastavíte délku na 9.

Je to na zodpovědnost programátora ujistit se, že datové typy jsou konvertibilní. Pokud se budete snažit provést INSERT řetězce 'MÉ NAROZENINY' do sloupce DATE, obdržíte při spuštění chybu.

Interní datové typy

Internal Oracle Datatype   Maximum Internal Length   Datatype Code  

VARCHAR2  

4000 bytes  

1  

NUMBER  

21 bytes  

2  

LONG  

2^31-1 bytes  

8  

ROWID  

10 bytes  

11  

DATE  

7 bytes  

12  

RAW  

2000 bytes  

23  

LONG RAW  

2^31-1 bytes  

24  

CHAR  

2000 bytes  

96  

MLSLABEL  

255 bytes  

105  

User-defined type (object type, VARRAY, Nested Table)  

<N/A>  

108  

REF  

<N/A>  

111  

CLOB  

<N/A>  

112  

BLOB  

<N/A>  

113  

Externí datové typy

EXTERNAL DATATYPE   TYPE OF PROGRAM VARIABLE   OCI DEFINED CONSTANT  
NAME   CODE  

VARCHAR2  

1  

char[n]  

SQLT_CHR  

NUMBER  

2  

unsigned char[21]  

SQLT_NUM  

8-bit signed INTEGER  

3  

signed char  

SQLT_INT  

16-bit signed INTEGER  

3  

signed short, signed int  

SQLT_INT  

32-bit signed INTEGER  

3  

signed int, signed long  

SQLT_INT  

FLOAT  

4  

float, double  

SQLT_FLT  

Null-terminated STRING  

5  

char[n+1]  

SQLT_STR  

VARNUM  

6  

char[22]  

SQLT_VNU  

LONG  

8  

char[n]  

SQLT_LNG  

VARCHAR  

9  

char[n+sizeof(short integer)]  

SQLT_VCS  

ROWID  

11  

char[n]  

SQLT_RID (see note 1)  

DATE  

12  

char[7]  

SQLT_DAT  

VARRAW  

15  

unsigned char[n+sizeof(short integer)]  

SQLT_VBI  

RAW  

23  

unsigned char[n]  

SQLT_BIN  

LONG RAW  

24  

unsigned char[n]  

SQLT_LBI  

UNSIGNED INT  

68  

unsigned  

SQLT_UIN  

LONG VARCHAR  

94  

char[n+sizeof(integer)]  

SQLT_LVC  

LONG VARRAW  

95  

unsigned char[n+sizeof(integer)]  

SQLT_LVB  

CHAR  

96  

char[n]  

SQLT_AFC  

CHARZ  

97  

char[n+1]  

SQLT_AVC  

ROWID descriptor  

104  

OCIRowid  

SQLT_RDD  

MLSLABEL  

106  

char[n]  

SQLT_LAB  

NAMED DATA TYPE  

108  

struct  

SQLT_NTY  

REF  

110  

OCIRef  

SQLT_REF  

Character LOB  

112  

OCILobLocator (see note 3)  

SQLT_CLOB  

Binary LOB  

113  

OCILobLocator (see note 3)  

SQLT_BLOB  

Binary FILE  

114  

OCILobLocator  

SQLT_FILE  

OCI string type  

155  

OCIString  

SQLT_VST (see note 2)  

OCI date type  

156  

OCIDate  

SQLT_ODT (see note 2)  

Notes:

(1) This type is valid only for version 7.x OCI calls. Oracle8 OCI applications should use the ROWID descriptor (type 104).

(2) For more information on the use of these datatypes, refer to Chapter 9, "Object-Relational Datatypes".

(3) In applications using datatype mappings generated by OTT, CLOBs may be mapped as OCIClobLocator, and BLOBs may be mapped as OCIBlobLocator. For more information, refer to Chapter 12, "Using the Object Type Translator".  

Následující 3 typy jsou interní v PL/SQL a nemohou být vráceny jako hodnoty OCI-čkem: Boolean,SQL_BOL , Indexed Table,SQLT_TAB , Record,SQLT_REC.

VARCHAR2

Proměnný řetězec do délky 4000 bytů.

Vstup: parametr values_sz určuje délku ve volání OCIBindByName nebo OCIBindByPos. Pokud je 0, interpretuje se jako NULL.

Výstup: Specifikujte požadovanou délku pro návratové volání v parametru value_sz volání OCIDefineByPos nebo ve volání OCIBindByName nebo OCIDefineByPos pro PL/SQL bloky. Pokud je délka 0, nejsou vrácena žádná data.

NUMBER

Neměli byste používat NUMBER jako externí datový typ. Pokud jej použijete, Oracle vrací numerickou hodnotu ve svém 21-bytovém binárním formátu a bude očekávat tento formát na vstupu.

1. byte je exponent, následuje 1-20 bytů mantisy. Nejvyšší bit exponentu je znaménkový. Nižších 7 bitů representuje exponent, který má základ 100 číslic s offsetem 65. ...

INTEGER

Konvertuje čísla. Je to znaménkové binární číslo, velikost je závislá na systému. Délka je vyžadována pro vstup i výstup. pokud je vráceno z Oraclu něco, co není integer, je vrácena použitelná část bez hlášení chyby. Při přetečení se generuje chyba.

FLOAT

Pro čísla desetinná nebo která přesahují INTEGER. Reprezentace závisí na hostitelském formátu. Normálně je délka buď 4 nebo 8 bytů. Délku je potřeba specifikovat pro vstup i výstup.

STRING

Je-li zakončen \0, chová se jako VARCHAR2, kromě toho musí končit na \0. Vhodné pro C.

Vstup --- délka je podporována ve volání OCIBindByName nebo OCIBindByPos limituje scanování pro ukončovač \0. Pokud tento není nalezen v této délce, generuje se chyba. Pokud délka není specifikována ve svázaném volání, OCI použitje maximální délku, tj. 4000. minimální délka jsou 2 byty. Pokud je 1. znak \'0 a délka jsou 2, je do sloupku vložena 0.

Výstup --- Na konec vráceného řetězce je přidán \0. Pokud řetězec zasahuje mimo specifikovanou délku, je oříznut a na poslední místo je dána \0.

VARNUM

Je to jako datový typ NUMBER, akorát 1. byte obsahuje délku reprezentace čísla (vyjma tohoto 1. délkového bytu). Např.:
Decimal Value   Length Byte   Exponent Byte   Mantissa Bytes   Terminator Byte  

0  

1  

128  

n/a  

n/a  

5  

2  

193  

6  

n/a  

-5  

3  

62  

96  

102  

2767  

3  

194  

28, 68  

n/a  

-2767  

4  

61  

74, 34  

102  

100000  

2  

195  

11  

n/a  

1234567  

5  

196  

2, 24, 46, 68  

n/a  

LONG

Obsahuje řetězce delší než 4000 bytů. Je možno uchovávat až do 2 gigabytů (2^31-1 bytů) ve sloupci LONG. Nemohou být použity ve funkcích, výrazech nebo v klausuli WHERE. Jsou konvertovány do a z řetězce.

VARCHAR

Pro řetězce proměnné délky. 1. dva byty popisují délku řetězce a zbývající část je řetězec. Specifikovaná délka řetězce ve vázaném definičním volání musí zahrnovat první 2 byty. Nejdelší řetězec tedy může být 65533 bytů, ne 65535. Pro konverzi větších řetězců se používá LONG VARCHAR.

ROWID

Rozpoznává části řádky v databázové tabulce. Může to být seznam položek v dotazu ze selectem. Např:

SELECT rowid, ename, sal FROM emp FOR UPDATE OF sal

Je možno použít ROWID v dalším příkazu INSERT, UPDATE či DELETE. Může to být rychlejší přístup k části řádky.

DATE

Může updatovat vkládat či načítat hodnoty dat použitím interního Oracle binárního formátu datumu. Tento formát obsahuje 7 bytů viz v tabulce.
Byte   1   2   3   4   5   6   7  

Meaning  

Century  

Year  

Month  

Day  

Hour  

Minute  

Second  

Example
(for 30-NOV-1992, 3:17 PM)  

119  

192  

11  

30  

16  

18  

1  

Století a rok jsou v notaci excess-100. Data BEFORE COMMON AREA jsou menší než 100. Letopočet začíná 01-JAN-4712 BCE, což je 1. den Juliánského kalendáře. Pokud není čas zadán, bere se půlnoc 1, 1, 1.

Pokud je tento sloupec konvertován na řetězec ve vašem programu, je vrácen defaultní formátovácí maska pro vaše spojení, či specifikovaná v souboru INIT.ORA.

Pokud používáte objekty v Oracle8, můžete pracovat se speciálním typem OCIDate.

RAW

Používaný pro binární data či řetězce bytů, které nejsou interpretovány v Oracle, např. uchovat sekvence grafických znaků. Největší délka je 2000 bytů.

Jsou-li V tabulce, jsou konvertovány na řetězec znaků v programu, data jsou reprezentována v hexadecimálním kódu. V programu je nutno při případném vkládání do tohoto typu použít hexadecimální kód.

Je možno použít volání OCIDefineByPos,OCIBindByName,OCIStmtSetPieceInfo.

Užívate-li objekty v Oracle8, můžete pracovat se speciálním typem OCIRaw.

VARRAW

Podobné RAW, nicméně první 2 byty popisují délku řetězce. Dále viz VARCHAR.

LONG RAW

Je podobný jako RAW, ale může uchovávat data do 2 GB.

UNSIGNED

Pro neznaménkové dlouhé integery. Délka je systémově závislá. Dále viz INTEGER.

LONG VARCHAR

Uchovává data z a do sloupců s typem LONG. První 4 byty obsahují délku položky. Takže maximální délka je 2^31-5 bytů.

LONG VARRAW

K uchování dat z a do sloupců s typem LONG RAW. Délka je v prvních 4 bytech.

CHAR

Pro řetězce s maximální délkou 2000.

Vstup: Délka je určena parametrem value_sz ve volání OCIBindByName či OCIBindByPos. Není povolena menší hodnota než 0.

Výstup specifikovaná délka je v parametru value_sz ve volání OCIDefineByPos. Parametr je nastaven na 0, nejsou vrácena žádná data. Pokud pominete parametr rlenp ve volání OCIDefineByPos, vracející hodnota je čistě vyplněná do délky bufferu. Null je vrácen jako řetězec prázdných znaků.

CHARZ

Podobný jako typ CHAR, akorát string musí být na vstupu ukončen \0 a při výstupu Oracle přidává \0. Tento znak pouze při vstupu/výstupu, nikoli v datech v tabulce.

Na vstupu, délka parametru musí znamenat přesnou délku, včetně '\0'.

MLSLABEL

Spolehlivý Oracle poskytuje tento datový typ, který uchovává vnitřní reprezentaci labelů generovanách víceúrovňovou ochranou systému. Spolehlivý Oracle používá labely ke kontrole databázového přístupu.

Nové OCI 8.0 Externí datové typy

Tyto datové typy nejsou v serveru Oracle7.

NAMED DATA TYPE

To jsou uživatelem definované typy, které jsou specifikovány v příkaze SQL: CREATE TYPE. Např. pro objektové typy, pole, vhnízděné tabulky. V C-čkových aplikacích jsou reprezentovány jako struktury. Koresponduje to s typy OCI_TYPECODE_OBJECT.

REF

To je odkaz na NAMED DATA TYPE. V C-čkové reprezentaci REF je proměnná deklarovaná jako typ OCIREF *.

Přístup k REF je možný pouze, pokud OCI aplikace byla inicializována v objectovém módu. Pokud jsou REFs natahovány ze serveru, jsou uchovávány na straně klienta. K alokaci REF pro použití ve vaší aplikaci, měli byste použít a deklarovat proměnnou jako pointer na REF a potom zavolat OCIObjectNew, a za parametr typecode použít OCI_TYPECODE_REF.

LOB

(Large Object) uchovává binární či znaková data do délky 4 gigabytů. Binární data jsou uchovávána v BLOB --- Binary LOB, znaková dat v CLOB či NCLOB --- NAtional Character LOB.

Mohou i nemusí být uloženy přímo s ostatními daty z řádky v databázi. Mají plnou transkační podporu db. serveru. Databázová tabulka uchovává LOB vyhledávač, který ukazuje na hodnotu LOB, která může být v jiném uchovávacím místě.

Pokud OCI aplikace pracuje s SQL dotazem, který obsahuje sloupkem typu LOB, načítá výsledek dotazu vracející locator /umisťovač/. V OCI se LOB locator mapuje do proměnné typu OCILobLocator. OCI funkce předpokldádají, že locator už byl vytvořen. Vázání a definování operací je vykonáváno v LOB locatoru, alokováno pomocí OCIDescriptorAlloc --- funkce. Locator je vždy načítán vždy nejprve SQL či OCIObjectPin a potom operací na locatoru jsou použity. OCI funkce nikdy neberou aktuální hodnotu LOB jako parametr.

Datové typy jsou dostupné pro vázání a definování LOBu jsou: SQLT_BLOB, SQLT_CLOB.

NCLOB je speciální typ CLOB s následujícími požadavky: k zápisu či vypsání NCLOB, uživatel musí nastavit znakovou sadu formou csfrm parametru v SQLCS_NCHAR, parametr amount ve volání zahrnujícím CLOBS či NCLOBS je vždy interpretován jako termy znaků spíše než bytů.

FILE

Poskytuje přístup k souboru LOBs, které jsou uchovávány ve filesystemu mimo databázi Oracle8. Oracle8 nyní podporuje přístup k binárním souborům či BFILEům.

Sloupek nebo atribut BFILE uchovává souborový LOB locator, který slouží jako pointer na binární soubor na serveru file-systemu. Locator obsahuje adresář a název souboru.

Binární soubory LOBs se neúčastní v transakcích. Největší podporovaná velikost souboru je 4 GB. Administrátor databáze musí zajistit, aby soubor existoval a aby Oracle8 proces měl čtecí práva na soubor.

BFILE typ povoluje read-only podporu rozsáhlejších binárních souborů. Nemůžete modifikovat přes Oracle. Oracle8 poskytuje rozhraní k přístupu k datům souboru. Primární interface, který používáte k přístupu k datům v souboru, jsou PL/SQL DBMS_LOB balíky a OCI.

Kód datového typu dostupný pro vázání a definování FILEs je SQLT_BFILE, tj. binární FILE LOB datový typ.

BLOB

Uchovává nestrukturované binární rozsáhlé objekty. BLOBy mohou být chápány jako bitové streamy bez sémantiky znaku. Mohou uchovávat 4 GB binárních dat.

BLOBy mají plnou transkační podporu, změny provedené pomocí PL/SQL DBMS_LOG balíky nebo použitím OCI se plně účastní transakcí. Manipulace hodnot BLOB může být committována nebo rollbackována. Není možno uložit BLOB locator v PL/SQL či v OCI proměnnév jedné transakci a pak to použít v jiné transakci či spojení.

CLOB

Uchovává jednoduché byte znaková data. Proměnná velikost znakových sad není podporována. Může uchovávat 4 GB znakových dat.

CLOBy mají plnou transkační podporu --- viz BLOB.

NCLOB

NCLOB je národní znaková verse CLOBu. Uchovává pevně velké jedno či více bytové národní znakové sady (NCHAR) data. dále viz CLOB.

Není možné vytvořit object s atributy NCLOB, ale je možno specifikovat NCLOB parametry v metodách.

Nové C data typy mapování

OCI nyní nabízí podporu pro Oraclem definované C-čkové datové typy používané k mapování uživateléem definovaných datových typů a ADT atributů do C reprezentace. OCI nabízí sadu volání k operování s těmito datovými typy...

Datové konverze

Následující tabulka ukazuje podporované konverze z interních ORACLE datových typů do vnitřní sloupcové reprezentace. Informace o konverzích nových typů ve verzi 8.0 je zde: REF v db jsou konvertovány na výstup na SQLT_REF; naopak z vnitřní reprezentace na vstup; NAMED DATA Types uchovávané v databázi mohou být konvertovány na SQLT_NTY a reprezentovány C-čkovou strukturou v aplikaci na výstupu; Podobně naopak z vnitřní reprezentace je SQLT_NTY na odpovídající typ na vstupu; LOBy a BFILEs jsou reprezentovány deskriptory v OCI aplikacích, takže žádné vstupní ani výstupní konverze nejsou prováděny.
EXTERNAL DATATYPES   INTERNAL DATATYPES  
1
VARCHAR2
 
2
NUMBER
 
8
LONG
 
11
ROWID
 
12
DATE
 
23
RAW
 
24
LONG RAW
 
96
CHAR
 
105
MLSLABEL
 

1 VARCHAR  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I/O(3)  

 

I/O(7)  

2 NUMBER  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

3 INTEGER  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

4 FLOAT  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

5 STRING  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I/O(3, 5)  

I/O  

I/O(7)  

6 VARNUM  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

7 DECIMAL  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

8 LONG  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I/O(3, 5)  

I/O  

I/O(7)  

9 VARCHAR  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I/O(3, 5)  

I/O  

I/O(7)  

11 ROWID  

I  

 

I  

I/O  

 

 

 

I  

 

12 DATE  

I/O  

 

I  

 

I/O  

 

 

I/O  

 

15 VARRAW  

I/O(6)  

 

I(5, 6)  

 

 

I/O  

I/O  

I/O(6)  

 

23 RAW  

I/O(6)  

 

I(5, 6)  

 

 

I/O  

I/O  

I/O(6)  

 

24 LONG RAW  

O(6)  

 

I(5, 6)  

 

 

I/O  

I/O  

O(6)  

 

68 UNSIGNED  

I/O(4)  

I/O  

I  

 

 

 

 

I/O(4)  

 

94 LONG VARCHAR  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I/O(3, 5)  

I/O  

I/O(7)  

95 LONG VARRAW  

I/O(6)  

 

I(5, 6)  

 

 

I/O  

I/O  

I/O(6)  

 

96 CHAR  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I(3)  

I/O  

I/O(7)  

97 CHARZ  

I/O  

I/O  

I/O  

I/O(1)  

I/O(2)  

I/O(3)  

I(3)  

I/O  

I/O(7)  

104 ROWID DESC.  

 

 

 

 

 

 

 

 

 

106 MLSLABEL  

 

 

 

 

 

 

 

 

I/O(8)  

Notes:

(1) For input, host string must be in Oracle ROWID format.
On output, column value is returned in Oracle ROWID format.

(2) For input, host string must be in the Oracle DATE character format.
On output, column value is returned in Oracle DATE format.

(3) For input, host string must be in hex format.
On output, column value is returned in hex format.

(4) For output, column value must represent a valid number.

(5) Length must be less than or equal to 2000.

(6) On input, column value is stored in hex format.
On output, column value must be in hex format.

(7) For input, host string must be a valid OS label in text format.
On output, column value is returned in OS label text format.

(8) For character representation of MLSLABEL, use the TO_CHAR(mlscolumn) function.  

Legend:

I = Conversion valid for input only

O = Conversion valid for output only

I/O = Conversion valid for input or output  

Typecodes

Je jednotný vzor kódu /typecode/ asociovaný s každým typem Oracle8, zda je skalár, sbírka, pointer nebo objektový typ. Tento vzor identifikuje typ a je používán v Oracle k řízení informací o objektových typech atributů.

CREATE TYPE my_type AS OBJECT

( attr1 NUMBER,

attr2 INTEGER,

attr3 SMALLINT)

CREATE TABLE my_table AS TABLE OF my_type; Tyto věci vytvoří objektový typ a objektovou tabulku. Když je vytvořen, my_table bude třísloupcová, každý je NUMBER typu, protože SMALLINT a INTEGER se mapuje vnitřně na NUMBER. Další info --- viz manuál.