LXXVII. Funzioni Oracle 8

Introduzione

Queste funzioni permettono di accedere ai database Oracle9, Oracle8 e Oracle7. Usano la Oracle Call Interface (OCI).

Questa estensione Ŕ pi¨ flessibile della estensione precedente di Oracle. Supporta il binding di variabili PHP locali e globali ai segnaposto Oracle, ha pieno supporto di LOB, FILE e ROWID e permette di utilizzare variabili di definizione personalizzabili. Si raccomanda di utilizzare questa estensione al posto della vecchia estensione quando possibile;

Requisiti

Occorre avere installate le librerie client di Oracle per utilizzare questa estensione. Gli utenti Windows necessitano almeno della versione 8.1 di Oracle per utilizzare la dll php_oci8.dll.

Prima di usare questa estensione, occorre sincerarsi di aver impostato le variabili d'ambiente per l'utente Oracle, come pure per l'utente del server web. Le variabili che potrebbero necessitare l'impostazione sono le seguenti:

  • ORACLE_HOME

  • ORACLE_SID

  • LD_PRELOAD

  • LD_LIBRARY_PATH

  • NLS_LANG

  • ORA_NLS33

Dopo aver impostato le variabili d'ambiente per l'utente del server web, occorre sicerarsi di aver aggiunto anche l'utente stesso (nobody, www) al gruppo oracle.

Se il server web non parte o va in blocco: Controllare che apache sia linkato con la libreria pthread:

# ldd /www/apache/bin/httpd 
    libpthread.so.0 => /lib/libpthread.so.0 (0x4001c000)
    libm.so.6 => /lib/libm.so.6 (0x4002f000)
    libcrypt.so.1 => /lib/libcrypt.so.1 (0x4004c000)
    libdl.so.2 => /lib/libdl.so.2 (0x4007a000)
    libc.so.6 => /lib/libc.so.6 (0x4007e000)
    /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

Se la libpthread non compare nell'elenco, occorre reinstallare Apache:

# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install

Si noti che su alcuni sistemi, come ad esempio UnixWare, la libreria si chiama libthread invece di libpthread. PHP e Apache devono essere configurati con EXTRA_LIBS=-lthread.

Installazione

Si deve compilare PHP con l'opzione --with-oci8[=DIR], dove DIR Ŕ di default il contenuto della variabile di ambiente ORACLE_HOME.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione Ŕ stata compilata nel PHP o se Ŕ stata caricata dinamicamente a runtime.

OCI_DEFAULT (integer)

ModalitÓ di esecuzione dello statement. Non viene eseguito il commit automatico utilizzando questa modalitÓ.

OCI_DESCRIBE_ONLY (integer)

ModalitÓ di esecuzione dello statement. Utilizzare questa modalitÓ se non si vuole eseguire la query, ma solamente ricevere la descrizione della select list.

OCI_COMMIT_ON_SUCCESS (integer)

ModalitÓ di esecuzione dello statement. Vene eseguito automaticamente il commit dello statement dopo la chiamata della oci_execute().

OCI_EXACT_FETCH (integer)

ModalitÓ di recupero dati dello statement. Utilizzato quando l'applicazione conosce in anticipo quante righe verranno recuperate. Questa modalitÓ disattiva il prefetching negli Oracle release 8 o successivi. Il cursore viene eliminato dopo che le sono state caricate e ci˛ pu˛ determinare un utilizzo ridotto delle risorse del server.

OCI_SYSDATE (integer)

OCI_B_BFILE (integer)

Utilizzato con oci_bind_by_name() quando si collegano i BFILE.

OCI_B_CFILEE (integer)

Utilizzato con oci_bind_by_name() quando si collegano i CFILE.

OCI_B_CLOB (integer)

Utilizzato con oci_bind_by_name() quando si collegano i CLOB.

OCI_B_BLOB (integer)

Utilizzato con oci_bind_by_name() quando si collegano i BLOB.

OCI_B_ROWID (integer)

Utilizzato con oci_bind_by_name() quando si collegano i ROWID.

OCI_B_CURSOR (integer)

Utilizzato con oci_bind_by_name() quando si collegano i cursori, precedentemente allocati con oci_new_descriptor().

OCI_B_NTY (integer)

Utilizzato con oci_bind_by_name() quando si collegano i named data type.

OCI_B_BIN (integer)

SQLT_BFILEE (integer)

Alias di OCI_B_BFILE.

SQLT_CFILEE (integer)

Alias di OCI_B_CFILEE.

SQLT_CLOB (integer)

Alias di OCI_B_CLOB.

SQLT_BLOB (integer)

Alias di OCI_B_BLOB.

SQLT_RDD (integer)

Alias di OCI_B_ROWID.

SQLT_NTY (integer)

Alias di OCI_B_NTY.

OCI_FETCHSTATEMENT_BY_COLUMN (integer)

ModalitÓ di default di oci_fetch_all().

OCI_FETCHSTATEMENT_BY_ROW (integer)

ModalitÓ alternativa di oci_fetch_all().

OCI_ASSOC (integer)

Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array associative come risultato.

OCI_NUM (integer)

Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array enumerativo come risultato.

OCI_BOTH (integer)

Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array con indici sia associativi che numerici.

OCI_RETURN_NULLS (integer)

Utilizzato con oci_fetch_array() per ottenere elementi dell'array vuoti se il valore del campo Ŕ NULL.

OCI_RETURN_LOBS (integer)

Utilizzato con oci_fetch_array() per ottenere il valore del LOB invece del suo descrittore.

OCI_DTYPE_FILE (integer)

Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di FILE.

OCI_DTYPE_LOB (integer)

Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di LOB.

OCI_DTYPE_ROWID (integer)

Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di ROWID.

OCI_D_FILE (integer)

Alias di OCI_DTYPE_FILE.

OCI_D_LOB (integer)

Alias di OCI_DTYPE_LOB.

OCI_D_ROWID (integer)

Alias di OCI_DTYPE_ROWID.

Esempi

Esempio 1. Trucchi OCI

<?php
// by sergo at bacup dot ru

// Usare l'opzione OCI_DEFAULT nel comando execute per ritardare l'esicuzione
OCIExecute($stmt, OCI_DEFAULT);

// per ricevere i dati utilizzare (dopo il fetch):

$result = OCIResult($stmt, $n);
if (
is_object($result)) $result = $result->load();

// come comandi INSERT o UPDATE usare:

$sql = "insert into table (field1, field2) values (field1 = 'value',
field2 = empty_clob()) returning field2 into :field2"
;
OCIParse($conn, $sql);
$clob = OCINewDescriptor($conn, OCI_D_LOB);
OCIBindByName($stmt, ":field2", &$clob, -1, OCI_B_CLOB);
OCIExecute($stmt, OCI_DEFAULT);
$clob->save("some text");
OCICommit($conn);

?>

You can easily access stored procedures in the same way as you would from the commands line.

Esempio 2. Using Stored Procedures

<?php
// by webmaster at remoterealty dot com
$sth = OCIParse($dbh, "begin sp_newaddress( :address_id, '$firstname',
'$lastname', '$company', '$address1', '$address2', '$city', '$state',
'$postalcode', '$country', :error_code );end;"
);

// Questo codice richiama la stored procedure sp_newaddress, dove :address_id Ŕ
// una variabile in/out e :error_code Ŕ una variabile out.
// Quindi si effettua il binding:

   
OCIBindByName($sth, ":address_id", $addr_id, 10);
   
OCIBindByName($sth, ":error_code", $errorcode, 10);
   
OCIExecute($sth);

?>

Sommario
oci_bind_by_name --  Lega una variabile PHP ad un segnaposto Oracle
oci_cancel -- Interrompe la lettura del cursore
oci_close -- Closes Oracle connection
collection->append -- Appends an object to the collection
collection->assign -- Assigns a value to the collection from another existing collection
collection->assignElem -- Assigns a value to the element of the collection
collection->getElem -- Returns value of the element
collection->max -- Gets the maximum number of elements in the collection
collection->size -- Returns size of the collection
collection->trim -- Trims elements from the end of the collection
oci_commit -- Commits outstanding statements
oci_connect -- Establishes a connection to Oracle server
oci_define_by_name --  Uses a PHP variable for the define-step during a SELECT
oci_error -- Returns the last error found
oci_execute -- Executes a statement
oci_fetch_all -- Fetches all rows of result data into an array
oci_fetch_array -- Returns the next row from the result data as an associative or numeric array, or both
oci_fetch_assoc -- Returns the next row from the result data as an associative array
oci_fetch_object -- Returns the next row from the result data as an object
oci_fetch_row -- Returns the next row from the result data as a numeric array
oci_fetch -- Fetches the next row into result-buffer
oci_field_is_null -- Checks if the field is NULL
oci_field_name -- Returns the name of a field from the statement
oci_field_precision -- Tell the precision of a field
oci_field_scale -- Tell the scale of the field
oci_field_size -- Returns field's size
oci_field_type_raw -- Tell the raw Oracle data type of the field
oci_field_type -- Returns field's data type
collection->free -- Frees resources associated with collection object
descriptor->free -- Frees resources associated with descriptor
oci_free_statement --  Frees all resources associated with statement or cursor
oci_internal_debug -- Enables or disables internal debug output
lob->append -- Appends data from the large object to another large object
lob->close -- Closes LOB descriptor
oci_lob_copy -- Copies large object
lob->eof -- Tests for end-of-file on a large object's descriptor
lob->erase -- Erases a specified portion of the internal LOB data
lob->export -- Exports LOB's contents to a file
lob->flush -- Flushes/writes buffer of the LOB to the server
lob->import -- Imports file data to the LOB
oci_lob_is_equal -- Compares two LOB/FILE locators for equality
lob->load -- Returns large object's contents
lob->read -- Reads part of large object
lob->rewind -- Moves the internal pointer to the beginning of the large object
lob->save -- Saves data to the large object
lob->seek -- Sets the internal pointer of the large object
lob->size -- Returns size of large object
lob->tell -- Returns current position of internal pointer of large object
lob->truncate -- Truncates large object
lob->writeTemporary -- Writes temporary large object
lob->write -- Writes data to the large object
oci_new_collection -- Allocates new collection object
oci_new_connect -- Establishes a new connection to the Oracle server
oci_new_cursor -- Allocates and returns a new cursor (statement handle)
oci_new_descriptor -- Initializes a new empty LOB or FILE descriptor
oci_num_fields --  Returns the number of result columns in a statement
oci_num_rows -- Returns number of rows affected during statement execution
oci_parse -- Prepares Oracle statement for execution
oci_password_change -- Changes password of Oracle's user
oci_pconnect -- Connect to an Oracle database using a persistent connection
oci_result -- Returns field's value from the fetched row
oci_rollback -- Rolls back outstanding transaction
oci_server_version -- Returns server version
oci_set_prefetch -- Sets number of rows to be prefetched
oci_statement_type -- Returns the type of an OCI statement
ocibindbyname --  Bind a PHP variable to an Oracle Placeholder
ocicancel -- Interrompe la lettura del cursore
ocicloselob -- Closes lob descriptor
ocicollappend -- Aggiunge un oggetto alla collezione
ocicollassign -- Assegna una collezione da un'altra collezione esistente
ocicollassignelem -- Assegna un elemento alla collezione in una specifica posizione
ocicollgetelem -- Coming soon
ocicollmax -- Coming soon
ocicollsize -- Coming soon
ocicolltrim -- Coming soon
ocicolumnisnull -- Verifica se un campo di risultato Ŕ NULL
ocicolumnname -- Restituisce il nome di un campo
ocicolumnprecision -- Coming soon
ocicolumnscale -- Coming soon
ocicolumnsize -- Restituisce la dimensione del campo
ocicolumntype -- Restituisce il tipo di dati di un campo
ocicolumntyperaw -- Coming soon
OCICommit -- Esegue le transazioni in sospeso
OCIDefineByName --  Utilizza una variabile PHP per la fase di definizione in un comando SELECT
OCIError -- Restituisce l'ultimo errore di stmt|conn|global
ociexecute -- Esegue un comando SQL
ocifetch -- Estrae la prossima tupla opnendola nel buffer di risultato.
ocifetchinto -- Estrae la prossima tupla ponendola in un array
ocifetchstatement -- Estrae tutte le tuple in un array
ocifreecollection -- Coming soon
ocifreecursor --  Libera tutte le risorse associate ad un cursore
ocifreedesc -- Cancella un descrittore di oggetto binario (LOB)
ocifreestatement --  Libera tutte le risorse associate ad un'istruzione
lob->getBuffering -- Returns current state of buffering for large object
ociinternaldebug --  Abilita o disabilita la visualizzazione del debug interno.
ociloadlob -- Coming soon
ocilogoff -- Disconnette da Oracle
ocilogon -- Stabilisce una connessione a Oracle
ocinewcollection -- Coming soon
ocinewcursor --  Restituisce un nuovo cursore (Statement-Handle)
ocinewdescriptor --  Inizializza un nuovo descrittore LOB/FILE vuoto
ocinlogon -- Stabilisce, una nuova connessione a Oracle.
ocinumcols --  Restituisce il numero di campi che risultano da un comando SQL
ociparse -- Analizza una query e restituisce un'istruzione.
ociplogon --  Stabilisce una connessione permanente a Oracle.
ociresult -- Restituisce il valore di campo della tupla estratta
ocirollback -- Annulla le transazioni in sospeso
ocirowcount -- Restituisce il numero di tuple modificate
ocisavelob -- Coming soon
ocisavelobfile -- Coming soon
ociserverversion -- Restituisce una stringa contenente informazioni sulla versione del server
lob->setBuffering -- Changes current state of buffering for large object
ocisetprefetch -- Imposta il numero di tuple da precaricare
ocistatementtype -- Restituisce il tipo di un'istruzione OCI
ociwritelobtofile -- Coming soon
ociwritetemporarylob -- Writes temporary blob