ODBC polecenia i funkcje

Transkrypt

1 odbc_autocommit ODBC polecenia i funkcje Funkcja wywołana bez parametru $onoff zwraca stan mechanizmu automatycznego zatwierdzania dla połączenia $connection_id. Jeżeli automatyczne zatwierdzanie jest włączone, zwraca True natomiast False, jeżeli jest wyłączone lub wystąpił błąd. Jeżeli parametr $onoff ma wartość True, automatyczne zatwierdzanie jest włączane, jeżeli ma wartość False wyłączane. Zwraca True w przypadku sukcesu i False w przypadku błędu. Domyślnie automatyczne zatwierdzanie jest włączone dla połączenia. Wyłączenie automatycznego zatwierdzania jest ekwiwalentem rozpoczęcia transakcji. Patrz również: odbc_commit() i odbc_rollback(). int odbc_autocommit (int connection_id [, int OnOff]) odbc_binmode int odbc_binmode (int result_id, int mode) (Funkcja ma wpływ na typy SQL ODBC: BINARY, VARBINARY i LONGVARBINARY) ODBC_BINMODE_PASSTHRU Dane BINARY są przekazywane dalej. ODBC_BINMODE_RETURN Zwraca w takiej postaci jak otrzymał ODBC_BINMODE_CONVERT Konwertuje znaki i końce linii. Gdy dane binarne SQL są konwertowane do danych znakowych C, każdy bajt (8 bitów) źródła jest reprezentowany jako dwa znaki ASCII. Znaki te są znakami ASCII reprezentującymi liczbę w postaci szesnastkowej. Na przykład, liczba binarna jest konwertowana na "01" natomiast na "FF". Obsługa typu LONGVARBINARY Tryb binarny longreadlen Wynik ODBC_BINMODE_PASSTHRU 0 przelotka ODBC_BINMODE_RETURN 0 przelotka ODBC_BINMODE_CONVERT 0 przelotka ODBC_BINMODE_PASSTHRU 0 przelotka ODBC_BINMODE_PASSTHRU >0 przelotka ODBC_BINMODE_RETURN >0 zwraca w niezmienionej postaci ODBC_BINMODE_CONVERT >0 zwraca jako ciąg znaków Jeżeli zostanie użyta funkcja odbc_fetch_into(), przelotka oznacza, że dla tych kolumn zwracany jest pusty ciąg. Jeżeli $result_id jest równy 0, ustawienia te są wartościami domyślnymi dla nowych wyników. odbc_close Zamyka połączenie do serwera bazy danych skojarzonego z podanym identyfikatorem łącza. Funkcja ta się nie uda, jeżeli na tym połączeniu są otwarte transakcje. W takim przypadku połączenie pozostanie otwarte. void odbc_close (int connection_id) - 1 -

2 odbc_close_all Zamyka wszystkie połączenia do serwera bazy danych. Funkcja ta się nie uda, jeżeli na tym połączeniu są otwarte transakcje. W takim przypadku połączenie pozostanie otwarte. void odbc_close_all (void) odbc_columnprivileges Zwraca listę kolumn i uprawnień do nich dla podanej tablicy. Zwraca identyfikator wyniku ODBC lub False w przypadku wystąpienia błędu. int odbc_columnprivileges (int connection_id [, string qualifier [, string owner [, string table_name [, string column_name]]]]) TABLE_QUALIFIER TABLE_OWNER TABLE_NAME GRANTOR GRANTEE PRIVILEGE IS_GRANTABLE Wynik jest uporządkowany według TABLE_QUALIFIER, TABLE_OWNER i TABLE_NAME. Argument $column_name pozwala na stosowanie wzorców przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak). odbc_columns Tworzy listę kolumn w określonym zakresie. Zwraca identyfikator wyniku ODBC lub False w przypadku wystąpienia błędu. int odbc_columns (int connection_id [, string qualifier [, string owner [, string table_name [, string column_name]]]]) Wynik składa się z następujących kolumn: TABLE_QUALIFIER TABLE_OWNER TABLE_NAME COLUMN_NAME DATA_TYPE TYPE_NAME PRECISION LENGTH SCALE RADIX NULLABLE REMARKS Wynik jest uporządkowany według TABLE_QUALIFIER, TABLE_OWNER i TABLE_NAME. Argument $column_name, $table_name i $column_name pozwalają na stosowanie wzorców przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak). Patrz również: odbc_columnprivileges(). odbc_commit Zwraca True w przypadku sukcesu lub False w przypadku błędu. Wszystkie transakcje rozpoczęte poprzez $connection_id są zatwierdzane. int odbc_commit (int connection_id) - 2 -

3 odbc_connect Zwraca identyfikator połączenia ODBC lub 0 (False) w przypadku błędu. Identyfikator połączenia zwracany przez tą funkcję jest wymagany przez inne funkcje ODBC. Możesz mieć jednocześnie wiele połączeń. Opcjonalny czwarty parametr określa typ kursora, jaki jest używany na tym połączeniu. Parametr ten nie jest zwykle wymagany, ale może być użyteczny przy obchodzeniu problemów ze sterownikami ODBC. W przypadku niektórych sterowników ODBC, wykonywanie skomplikowanych procedur przechowywanych mogą powodować błąd Cannot open a cursor on a stored procedure that anything other than a single select statement in it. Użycie SQL_CUR_USE_ODBC może pomóc uniknąć błędu. Niektóre sterowniki nie obsługują opcjonalnego parametru $row_number w odbc_fetch_row(). Parametr SQL_CUR_USE_ODBC może również pomóc w tym przypadku. int odbc_connect (string dsn, string user, string password [, int cursor_type]) Dla parametru $cursor_type zdefiniowane są następujące stałe: SQL_CUR_USE_IF_NEEDED SQL_CUR_USE_ODBC SQL_CUR_USE_DRIVER SQL_CUR_DEFAULT Dla połączyć trwałych patrz odbc_pconnect(). odbc_cursor Zwraca nazwę kursora dla podanego $result_id. string odbc_cursor (int result_id) odbc_do Uruchamia zapytanie na podanym połączeniu. int odbc_do (int conn_id, string query) odbc_exec Zwraca False w przypadku wystąpienia błędu. Zwraca identyfikator wyniku ODBC, jeżeli udało się poprawnie wykonać wyrażenie SQL. Funkcja odbc_exec() wysyła wyrażenie SQL do serwera bazy danych wskazywanego przez $connection_id. Parametr ten musi być prawidłowym identyfikatorem zwracanym przez odbc_connect() lub odbc_pconnect(). Patrz również: odbc_prepare() i odbc_execute() dla wielokrotnego wykonania wyrażenia SQL. int odbc_exec (int connection_id, string query_string) odbc_execute Wykonuje zapytanie przygotowanie za pomocą odbc_prepare(). Zwraca True w przypadku udanego wykonania, False w przeciwnym przypadku. Tablica $parameters_array jest potrzebna, jeżeli w wyrażeniu SQL występują parametry. int odbc_execute (int result_id [, array parameters_array]) - 3 -

4 odbc_fetch_into Zwraca ilość kolumn w wyniku lub False w przypadku wystąpienia błędu. Tablica $result_array musi być przekazana przez referencję, ale może być to dowolny typ, ponieważ zostanie skonwertowany na typ tablicowy. Tablica zawiera wartości kolumn pod indeksami rozpoczynającymi się od 0. int odbc_fetch_into (int result_id [, int rownumber, array result_array]) odbc_fetch_row Jeżeli funkcja się powiedzie (był wiersz wyniku) zwracana jest wartość True. Jeżeli nie ma już wierszy, zwracana jest wartość False. Funkcja pobiera wiersz danych zwróconych przez funkcję odbc_do() lub odbc_exec(). Po wywołaniu odbc_fetch_row() pola z wyniku są dostępne dla funkcji odbc_result(). Jeżeli nie zostanie podany parametr $row_number, funkcja próbuje pobrać kolejny wiersz wyniku. Wywołania funkcji odbc_fetch_row() z parametrem $row_number i bez niego mogą być mieszane. Aby więcej niż raz odczytać wyniki zapytania, należy wywołać odbc_fetch_row() z $row_number równym 1 i kontynuować pobieranie danych za pomocą odbc_fetch_row() bez parametru $row_number. Jeżeli sterownik nie obsługuje odczytywania wiersza o podanym numerze, parametr ten jest ignorowany. int odbc_fetch_row (int result_id [, int row_number]) odbc_field_len Zwraca długość pola wskazywanego przy pomocy numeru w wyniku ODBC o podanym identyfikatorze. Numerowanie pól rozpoczyna się od 1. Patrz również: odbc_field_scale(). int odbc_field_len (int result_id, int field_number) odbc_field_name Zwraca nazwę pola wskazywanego przy pomocy numeru w wyniku ODBC o podanym identyfikatorze. Numerowanie pól rozpoczyna się od 1. W przypadku wystąpienia błędu zwraca False. string odbc_field_name (int result_id, int field_number) odbc_field_num Zwraca numer kolumny o podanej nazwie w wyniku ODBC o podanym identyfikatorze. Numerowanie pól rozpoczyna się od 1. W przypadku wystąpienia błędu zwraca False. int odbc_field_num (int result_id, string field_name) odbc_field_precision Zwraca dokładność kolumny o podanym numerze w wyniku ODBC o podanym identyfikatorze. Patrz również: odbc_field_scale(). string odbc_field_precision (int result_id, int field_number) odbc_field_scale Zwraca skalę kolumny o podanym numerze w wyniku ODBC o podanym identyfikatorze. string odbc_field_scale (int result_id, int field_number) - 4 -

5 odbc_field_type Zwraca typ SQL pola wskazywanego przy pomocy numeru w wyniku ODBC o podanym identyfikatorze. Numerowanie pól rozpoczyna się od 1. string odbc_field_type (int result_id, int field_number) odbc_foreignkeys Odczytuje dane na temat kluczy obcych. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_foreignkeys (int connection_id, string pk_qualifier, string pk_owner, string pk_table, string fk_qualifier, string fk_owner, string fk_table) Wynik składa się z następujących kolumn: PKTABLE_QUALIFIER PKTABLE_OWNER PKTABLE_NAME PKCOLUMN_NAME FKTABLE_QUALIFIER FKTABLE_OWNER FKTABLE_NAME FKCOLUMN_NAME KEY_SEQ UPDATE_RULE DELETE_RULE FK_NAME PK_NAME Jeżeli parametr $pk_table zawiera nazwę tabeli, odbc_foreignkeys() zwraca w wynik zawierający klucz główny i wszystkie klucze obce odwołujące się do tej tabeli. Jeżeli $fk_table zawiera nazwę tabeli, odbc_foreignkeys() zwraca wynik zawierający wszystkie klucze obce w podanej tabeli oraz klucze główne, do których się odwołują. Jeżeli zarówno $pk_table jak i $fk_table zawierają nazwy tabel, odbc_foreignkeys() zwraca klucze obce z tabeli określonej przez $fk_table odwołujące się do klucza głównego z tabeli $pk_table. W większości przypadków będzie to tylko jeden klucz. odbc_free_result Zawsze zwraca True. Wywołanie tej funkcji jest wymagane jedynie wtedy, gdy skrypt zużywa zbyt dużo pamięci podczas pracy. Cała pamięć przydzielona do wyniku jest automatycznie zwalniana po zakończeniu działania skryptu. Jeżeli jesteś pewien, że nie będziesz już używał danych z wyniku, możesz wywołać funkcję odbc_free_result(), aby zwolnić pamięć przydzieloną do $result_id. Jeżeli automatyczne zatwierdzanie jest zablokowane, (patrz odbc_autocommit()) i wywołasz odbc_free_result() przed zatwierdzeniem, wszystkie otwarte transakcje zostaną wycofane. int odbc_free_result (int result_id) odbc_gettypeinfo Pobiera dane na temat typów danych obsługiwanych przez źródło danych. Zwraca identyfikator wyniku ODBC lub False w przypadku wystąpienia błędu. Można użyć opcjonalnego parametru $data_type do ograniczenia danych do jednego typu. int odbc_gettypeinfo (int connection_id [, int data_type]) Wynik składa się z następujących kolumn: TYPE_NAME DATA_TYPE PRECISION LITERAL_PREFIX LITERAL_SUFFIX CREATE_PARAMS NULLABLE CASE_SENSITIVE SEARCHABLE UNSIGNED_ATTRIBUTE MONEY AUTO_INCREMENT LOCAL_TYPE_NAME MINIMUM_SCALE MAXIMUM_SCALE Wynik jest uporządkowany według DATA_TYPE i TYPE_NAME

6 odbc_longreadlen (Funkcja ma wpływ na typ SQL ODBC LONG i LONGVARBINARY) Ilość bajtów zwracanych do PHP jest określana przez wartość parametru. Jeżeli ma wartość 0, dane z kolumn long są przepuszczane do klienta. Obsługa kolumn LONGVARBINARY jest również realizowana przez odbc_binmode(). int odbc_longreadlen (int result_id, int length) odbc_num_fields Zwraca ilość pól (kolumn) w wyniku ODBC. Funkcja zwraca -1 w przypadku wystąpienia błędu. Argumentem jest prawidłowy identyfikator wyniku zwracany przez odbc_exec(). int odbc_num_fields (int result_id) odbc_num_rows Zwraca ilość wierszy w wyniku ODBC. W przypadku wystąpienia błędu funkcja zwraca -1. Dla wyrażeń INSERT, UPDATE i DELETE funkcja zwraca ilość zmienionych wierszy. Dla wyrażeń SELECT zwraca ilość zwracanych wierszy. Użycie funkcji odbc_num_rows() do sprawdzenia ilości wierszy dostępnych po wykonaniu wyrażenia SELECT zwróci dla wielu sterowników -1. int odbc_num_rows (int result_id) odbc_pconnect Zwraca identyfikator połączenia ODBC lub 0 (False) w przypadku wystąpienia błędu. Funkcja jest podobna do odbc_connect(), poza tym, że połączenie nie jest zamykane po zakończeniu skryptu. Kolejne żądania połączenia z tą samą kombinacją $dsn, $user i $password (poprzez odbc_connect() i odbc_pconnect()) powodują ponowne wykorzystanie połączenia trwałego. Połączenia trwałe nie działają, jeżeli PHP jest użyty jako program CGI. Opis opcjonalnego parametru $cursor_type znajduje się przy opisie funkcji odbc_connect(). int odbc_pconnect (string dsn, string user, string password [, int cursor_type]) odbc_prepare Zwraca False w przypadku błędu. Zwraca identyfikator wyniku ODBC dla poprawnie przygotowanego wyrażenia SQL. Wynikowy identyfikator może być użyty do uruchomienia wyrażenia za pomocą odbc_execute(). int odbc_prepare (int connection_id, string query_string) odbc_primarykeys Zwraca nazwy kolumn składających się na klucz główny tabeli. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_primarykeys (int connection_id, string qualifier, string owner, string table) Wynik posiada następujące kolumny: TABLE_QUALIFIER TABLE_OWNER TABLE_NAME COLUMN_NAME KEY_SEQ PK_NAME - 6 -

7 odbc_procedurecolumns Zwraca listę parametrów wejściowych i wyjściowych oraz kolumn będących wynikiem działania procedury. zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_procedurecolumns (int connection_id [, string qualifier [, string owner [, string proc [, string column]]]]) Wynik posiada następujące kolumny: PROCEDURE_QUALIFIER PROCEDURE_OWNER PROCEDURE_NAME COLUMN_NAME COLUMN_TYPE DATA_TYPE TYPE_NAME PRECISION LENGTH SCALE RADIX NULLABLE REMARKS Wynik jest posortowany według kolumn PROCEDURE_QUALIFIER, PROCEDURE_NAME i COLUMN_TYPE. Argumenty $owner, $proc i $column mogą zawierać wzorzec przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak). odbc_procedures Tworzy listę procedur w określonym zakresie. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_procedures (int connection_id [, string qualifier [, string owner [, string name]]]) PROCEDURE_QUALIFIER PROCEDURE_OWNER PROCEDURE_NAME NUM_INPUT_PARAMS NUM_OUTPUT_PARAMS NUM_RESULT_SETS REMARKS PROCEDURE_TYPE Argumenty $owner, $proc i $column mogą zawierać wzorzec przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak). odbc_result Zwraca zawartość pola. Parametr $field może być liczbą określającą numer pola lub ciągiem zawierającym nazwę pola. string odbc_result (int result_id, mixed field) Przykład: $item_3 = odbc_result ($Query_ID, 3); $item_val = odbc_result ($Query_ID, "val"); Pierwsze wywołanie odbc_result() zwraca wartość trzeciego pola w bieżącym rekordzie Drugie wywołanie funkcji odbc_result() zwraca wartość pola o nazwie val w bieżącym rekordzie w wyniku. Błąd wystąpi, jeżeli numer kolumny dla jest mniejsza od jeden lub przekracza ilość kolumn w bieżącym rekordzie. Podobnie błąd wystąpi, jeżeli podana nazwa nie jest nazwą pola znajdującego się w wyniku. Numery pól rozpoczynają się od 1. W zależności od trybu obsługi kolumn long, zwracane są dane binarne lub long. Patrz również: odbc_binmode() i odbc_longreadlen()

8 odbc_result_all Zwraca ilość wierszy w wyniku lub False w przypadku błędu. Funkcja odbc_result_all() powoduje wydruk wszystkich wierszy z wyniku tworzonego za pomocą odbc_exec(). Wynikiem funkcji jest tabela HTML. Dodatkowe formatowanie tabeli może być realizowane za pomocą opcjonalnego ciągu $format. int odbc_result_all (int result_id [, string format]) odbc_rollback Wycofuje transakcje otwarte poprzez połączenie $connection_id. Zwraca True w przypadku pomyślnego wykonania operacji lub False w przypadku błędu. int odbc_rollback (int connection_id) odbc_setoption Funkcja pozwala operować opcjami ODBC dla połączenia lub wyniku zapytania. Funkcja została napisana w celu umożliwienia znalezienia obejścia problemów ze sterownikami ODBC zawierającymi błędy. Powinieneś używać tej funkcji jedynie wtedy, gdy jesteś programistą ODBC i znasz konsekwencje ustawiania różnych opcji. Powinieneś również posiadać dobry podręcznik ODBC zawierający objaśnienie wszystkich opcji i ich wartości. Różne wersje sterowników obsługują różne opcje. int odbc_setoption (int id, int function, int option, int param) Ponieważ efekty mogą bardzo zależeć od sterownika ODBC, używanie tej funkcji w skryptach udostępnianych publicznie nie jest zalecane. Niektóre opcje ODBC nie są dostępne dla tej funkcji, ponieważ muszą być ustawiane przed nawiązaniem połączenia lub przygotowania zapytania. Jednak może ona pomóc w konkretnym przypadku. Parametr $id jest identyfikatorem połączenia lub identyfikatorem wyniku, na którym chcesz zmienić opcje. Dla SQLSetConnectOption() jest to identyfikator połączenia. Dla SQLSetStmtOption() jest to identyfikator wyniku. Parametr $function jest używaną funkcją ODBC. Wartością może być: 1 dla SQLSetConnectOption() i 2 dla SQLSetStmtOption(). Parametr $option jest wartością ustawianej opcji. Parametr $param jest wartością dla podanej opcji. Przykład: ODBC SetOption // 1. Opcje 102 dla SQLSetConnectOption() wynosi SQL_AUTOCOMMIT. // Wartość 1 dla SQL_AUTOCOMMIT to SQL_AUTOCOMMIT_ON. // Przykład ten jest analogiczny do wywołania // odbc_autocommit($conn, true); odbc_setoption ($conn, 1, 102, 1); // 2. Opcja 0 dla SQLSetStmtOption() wynosi SQL_QUERY_TIMEOUT. // Przykład ustawia czas wygaśnięcia zapytania na 30 sekund. $result = odbc_prepare ($conn, $sql); odbc_setoption ($result, 2, 0, 30); odbc_execute ($result); - 8 -

9 odbc_specialcolumns Gdy wartością parametru $type wynosi SQL_BEST_ROWID, funkcja odbc_specialcolumns() zwraca kolumnę lub kolumny, które jednoznacznie identyfikują każdy wiersz tabeli. Jeżeli $typ wynosi SQL_ROWVER, funkcja odbc_specialcolumns() zwraca optymalną kolumnę lub zestaw kolumn, która po odczytaniu wartości kolumny lub kolumn pozwala na jednoznaczną identyfikację wierszy z tablicy. Funkcja zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_specialcolumns (int connection_id, int type, string qualifier, string owner, string table, int scope, int nullable) SCOPE COLUMN_NAME DATA_TYPE TYPE_NAME PRECISION LENGTH SCALE PSEUDO_COLUMN Wynik jest uporządkowany według kolumny SCOPE. odbc_statistics Odczytuje statystyki na temat tablicy i indeksów. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_statistics (int connection_id, string qualifier, string owner, string table_name, int unique, int accuracy) TABLE_QUALIFIER TABLE_OWNER TABLE_NAME NON_UNIQUE INDEX_QUALIFIER INDEX_NAME TYPE SEQ_IN_INDEX COLUMN_NAME COLLATION CARDINALITY PAGES FILTER_CONDITION Wynik jest uporządkowany według kolumn: NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME i SEQ_IN_INDEX. odbc_tableprivileges Tworzy listę tabel w żądanym zakresie oraz uprawnień związanych z każdą tabelą. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_tableprivileges (int connection_id [, string qualifier [, string owner [, string name]]]) TABLE_QUALIFIER TABLE_OWNER TABLE_NAME GRANTOR GRANTEE PRIVILEGE IS_GRANTABLE Wynik jest uporządkowany według kolumn: TABLE_QUALIFIER, TABLE_OWNER i TABLE_NAME. Argumenty $owner, $proc i $column mogą zawierać wzorzec przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak)

10 odbc_tables Tworzy listę tabel w żądanym zakresie. Zwraca identyfikator wyniku ODBC lub False w przypadku błędu. int odbc_tables (int connection_id [, string qualifier [, string owner [, string name [, string types]]]]) TABLE_QUALIFIER TABLE_OWNER TABLE_NAME TABLE_TYPE REMARKS Wynik jest uporządkowany według: TABLE_TYPE, TABLE_QUALIFIER, TABLE_OWNER i TABLE_NAME. Argumenty $owner, $proc i $column mogą zawierać wzorzec przeszukiwania (% zastępuje zero lub więcej znaków i _ zastępuje jeden znak). Aby obsłużyć wyliczanie kwalifikatorów, właścicieli i typów tabel dostępna jest specjalna składnia parametrów $qualifier, $owner, $name i $table_type. Jeżeli $qualifier zawiera jeden znak procentu (%) natomiast $owner i $name są pustymi ciągami, wynik zawiera listę kwalifikatorów dla źródła danych (wszystkie kolumny poza TABLE_QUALIFIER zawierają wartości NULL). Jeżeli $owner zawiera znak procentu (%) a $qualifier i $name są pustymi ciągami, wynik jest listą właścicieli dla podanego źródła danych (wszystkie kolumny poza TABLE_OWNER zawierają wartości NULL). Jeżeli $table_type zawiera znak procentu (%) a $qualifier, $owner i $name są pustymi ciągami, wynik jest listą typów tabel dla podanego źródła danych (wszystkie kolumny poza TABLE_TYPE zawierają wartości NULL). Jeżeli $table_type nie jest pustym ciągiem, musi zawierać listę wartości rozdzielonych przecinkami interesujących typów tabel Każda wartość może być otoczona apostrofami (') lub bez apostrofów, na przykład: 'TABLE','VIEW' lub TABLE,VIEW. Jeżeli źródło danych nie obsługuje jakiegoś typu tabel, odbc_tables() nie zwraca wyników dla tego typu. Sposób odczytywania uprawnień opisany jest przy funkcji odbc_tableprivileges()