LOBy v OCI

K práci s LOBy se v OCI používají proměnné typu OCILobLocator reprezentující lokátory LOBů.
Tyto lokátory jsou používány všemi funkcemi, které pracují s LOBy.
Chceme-li s LOBem pracovat, je třeba alokovat jeho lokátor a inicializovat ho.

Alokace

Pro lokátor je třeba alokovat paměť funkcí OCIDescriptorAlloc, které předáme jako typ deskriptoru konstantu OCI_DTYPE_FILE (externí LOB) nebo OCI_DTYPE_LOB (interní LOB) - tyto lokátory nelze zaměňovat, ačkoliv jsou v C stejného typu.

OCIDescriptorAlloc(*environment,*lob,type,size,...)
Alokuje a vrací lokátor externího (type = OCI_DTYPE_FILE) nebo interního (OCI_DTYPE_LOB) LOBu.
Rezervuje pro něj paměť velikosti size.

OCIDescriptorFree(*locator,*type)
Uvolní lokátor a paměť, kterou měl alokovánu.

Inicializace

Před použitím lokátoru ho musíme inicializovat. Máme několik možností:

• provedením SELECT lob,... FROM ... FOR UPDATE + defining:
  
  1. OCIDescriptorAlloc();
  2. OCIStmtPrepare("SELECT lob FROM table FOR UPDATE");
  3. OCIDefineByPos();
  4. OCIStmtExecute(...,mode = OCI_DEFAULT);
  5. OCICommit();
  
  
• provedením INSERT/DELETE ... RETURNING :lob + binding
  1. OCIDescriptorAlloc();
  2. OCIStmtPrepare("INSERT INTO table(LOB) VALUES(EMPTY_CLOB()) RETURNING LOB INTO :lob ");
  3. OCIBindByPos() nebo OCIBindByName();
  4. OCIStmtExecute(...,mode = OCI_DEFAULT);
  5. OCICommit();
  
  
• přiřazením jiného (již inicializovaného) LOBu.
  
  
• funkcí OCIAttrSet() nastavit jeho atribut OCI_ATTR_LOBEMPTY, čímž dostaneme prázdný LOB, který může být použit pouze pro vložení do nějaké tabulky (UPDATE ... SET lob nebo INSERT ... VALUES(lob, ...))

Práce s LOBy

Když máme alokován interní LOB, lze z něj číst a zapisovat do něj. Do externího LOBu nelze přes OCI zapisovat.

OCILobRead(...,*lob,*buffer,buffer_length,offset,callback,...)
Načte specifikovanou část LOBu do bufferu.
Pokud nebyla načtena všechna požadovaná data, vrací funkce chybu OCI_NEED_DATA a aplikace může funkci volat znovu, dokud nedostane vše.
Data lze číst také callback funkcí, pokud je na ni předán ukazatel.

OCILobWrite(...)
Analogie funkce pro čtení.
Zapisovat však lze jen do interních LOBů.
Přemaže data uložená v LOBu novými.

OCILobWriteAppend(...)
Data se připisují na konec existujícího LOBu, není zde proto parametr offset.
Jinak podobné funkci OCILobWrite.

OCILobGetLength(...,*lob,*length)
Do length vloží délku LOBu, tj. počet znaků pro znakové LOBy nebo počet byte pro BLOB resp. BFILE.

Příklad použití od Oraclu:
cdemolb.h,cdemolb.c


Pro interní LOBy můžeme používat tyto funkce:

OCILobAppend(...,*src_lob,*dst_lob),
OCILobCopy(...,*src_lob,*dst_lob,amount,src_offset,dst_offset),
OCILobErase(...,*lob,amount,offset),
OCILobTrim(...,*lob,new_length),


Pro externí LOBy lze použít následující funkce:

OCILobFileOpen(...,*lob,OCI_FILE_READONLY)
Otevře na serveru soubor externího LOBu.

OCILobFileClose(...,*lob)
Uzavře na serveru soubor externího LOBu.

OCILobFileGetName(...,*lob,*directory_alias,*alias_length,*file_name,*name_length)
Vrací alias adresáře a název souboru LOBu.

OCILobFileSetName(...,*lob,*directory_alias,*alias_length,*file_name,*name_length)
Nastaví alias adresáře a název souboru LOBu.

OCILobFileIsOpen(...,*lob,*is_open)
Zjistí, zda je soubor otevřen.

OCILobFileExists(...,*lob,*is_exists)
Zjistí, zda soubor existuje.

Otevírání a uzavírání LOBů

Každý LOB na serveru může je buď otevřený nebo uzavřený.
Je-li s uzavřeným LOBem manipulováno, automaticky se otevře, provede se požadovaná operace a po skončení této operace se uzavře. Po uzavření LOBu se provedou triggery, jsou-li nějaké definovány.
Sérii úprav LOBu lze obklopit funkcemi pro otevření a uzavření LOBu tak, aby se během těchto úprav nevyvolávaly triggery.

OCILobOpen(...,*lob,mode),
Otevře LOB pro čtení (mode=OCI_LOB_READONLY) resp. čtení a zápis (mode=OCI_LOB_READWRITE).
Stejný účinek má také funkce OCILobOpen() používaná pro externí LOBy.

OCILobClose(...,*lob),
Uzavře LOB.
Stejný účinek má také funkce OCILobClose() používaná pro externí LOBy.

OCILobIsOpen(...,*lob,mode),
Zjistí, zda je LOB otevřen.

Bufferování dat LOBů u klienta

Při práci s interními LOBy lze zvýšit výkon aplikace, které provádí mnoho čtení nebo zápisů krátkých úseků LOBů.
Dosáhneme toho zapnutím bufferování na straně klienta.

OCILobEnableBuffering(...,*lob),
Zapne bufferování.

OCILobDisableBuffering(...,*lob),
Zruší bufferování.

OCILobFlushBuffer(...,*lob),
Zapíše obsah bufferu na server.


Některé funkce však nelze používat se zapnutým bufferováním:
OCILobAppend(), OCILobCopy(), OCILobErase(), OCILobGetLength(), OCILobLoadFromFile(), OCILobTrim(), OCILobWriteAppend()

Dočasné LOBy

Dočasné LOBy mají data uložena na serveru, avšak lokátor mají pouze u klienta.
Jejich životnost je omezena obvykle po dobu trvání session, lze ale nastavit jinak.
Na dočasný LOB je možné aplikovat funkce používané pro standardní LOBy.
Používají se jako lokální pomocné proměnné.

OCILobCreateTemporary(...,*lob,type,cache,duration),
Vytváří dočasný LOB, který je inicializován jako prázdný.
Typ LOBu je jedna z hodnot OCI_TEMP_BLOB, OCI_TEMP_CLOB, OCI_TEMP_NCLOB.
Parametr cache udává, zda se má na serveru umístit LOB do cache.
Dobu života LOBu lze ovlivnit parametrem duration:
OCI_DURATION_SESSION... LOB je automaticky zrušen po odhlášení,
OCI_DURATION_CALL ... LOB je zrušen po dokončení volání následující OCI funkce.

OCILobFreeTemporary(...,*lob),
Zruší dočasný LOB - lokátor i data.

OCILobIsTemporary(...,*lob),
Zjistí, zda je daný LOB dočasný.

Příklad použití od Oraclu:
TLOBS.C

<?php

/* Prihlaseni k databazi ************************************************/ 

  $connection = OciLogon("scott","tiger","DB");

/* Vytvoreni tabulky ****************************************************/ 
  
  $statement = OciParse($connection,
    "CREATE TABLE Tab(Jmeno VARCHAR(20), Data CLOB)");
  @OciExecute($statement);

  OciFreeStatement($statement);

/* Ulozeni LOBu do tabulky **********************************************/

  $statement = OciParse($connection,
    "INSERT INTO Tab(Jmeno,Data) 
     VALUES('lob.txt',EMPTY_CLOB()) 
     RETURNING Data INTO :lob");
  
  //Pripojeni lokatoru LOBu:
  $locator = OciNewDescriptor($connection,OCI_D_LOB);
  OciBindByName($statement,":LOB",&$locator,-1,OCI_B_CLOB);
  
  OciExecute($statement,OCI_DEFAULT);
  
  //Nacteni LOBu ze souboru:
  $locator->SaveFile("lob.txt");

  OciCommit($connection);
  
  OciFreeStatement($statement);

/* Nacteni LOBu z tabulky ***********************************************/
  
  $statement = OciParse($connection,"SELECT Jmeno,Data FROM Tab");
  
  OciExecute($statement,OCI_DEFAULT);

  while (OciFetch($statement))
  { $lob = OciResult($statement,"DATA");
    echo $lob->Load()."<BR>";
  }  

  OciCommit($connection);
  
  OciFreeStatement($statement);
?>