Bu bölümde, MySQL veritabanında kullanılan C API fonksiyonlarının bir bölümü ele alınmaktadır. Burada gösterilen fonksiyonların bildirimi mysql.h dosyası içinde yer almaktadır.
Açılmış olan bir bağlantıyı kapatır. mysql parametresi ile gsöterilen ve daha önceden mysql_init() veya mysql_connect() fonksiyonu ile oluşturulan bir bağlantı Handle değeri varsa, tahsis edilen belleği boşaltır.
Dönüş değeri
Yok.
Hata durumu
Yok.
mysql parametresi ile gösterilen bağlantı kapsamında kullanıldığında hata veren en son API fonksiyonu ile ilgili hata mesajını içeren NULL bir değer ile sonlandırılmış bir karakter dizisi geri verir. Eğer en son kullanılan API fonksiyonu hata vermezse, bu fonksiyon bir önceki hatayı gösteren bir karakter dizisi veya bir hata olmadığını gösteren boş bir karakter dizisi geri verir.
Dönüş değeri
Bir hata neydana geldiğinde, hata ile açıklama içeren ve NULL bir değer ile sonlandırılmış, hata meydana gelmemişse boş bir karakter dizisi geri döndürür.
Hata durumu
Yok.
mysql_store_result() fonksiyonu ile elde edilen result parametresi ile gösterilen veriden tabloda yer alan sütun (field) tanımlamalarını (alan adı, türü ve boyutu vb.) MYSQL_FIELD veri yapısına aktarır. Her alan (sütun) için MYSQL_FIELD yapısı bu fonksiyonunun tekrar tekrar kullanılmasıyla elde edilebilir. Eğer geride herhangi bir sütun yoksa NULL bir değer geri verir.
Her yeni SELECT query işleminde mysql_fetch_field() fonksiyonu ilk sütun (field) hakkında bilgi geri vermek üzere yenilenir. Ayrıca, mysql_field_seek() fonksiyonu bu fonksiyon tarafından geri verilen değeri etkiler.
Dönüş değeri
Aktif sütun (field) için MYSQL_FIELD yapı değerini, eğer geride herhangi bir sütun yoksa NULL bir değer geri verir.
Hata durumu
Yok.
mysql_store_result() fonksiyonu ile elde edilen result parametresi ile gösterilen veriden bir sonraki satır (row) değerlerini alır.
mysql_store_result() fonksiyonu ile elde edilen sonuçlarla kullanıldığında, mysql_fetch_row() fonksiyonu okunacak daha fazla satır değeri kalmadığında NULL bir değer geri verir.
mysql_use_result() fonksiyonundan sonra kullanıldığında, mysql_fetch_row() fonksiyonu okunacak daha fazla satır değeri kalmadığında veya bir hata meydana geldiğinde NULL bir değer geri verir.
mysql_num_fields() fonksiyonu ile bir tablodaki sütun (field) sayısı elde edilebildiğinden, mysql_fetch_row() fonksiyonunun geri verdiği değer 0'dan başlayarak mysql_num_fields() fonksiyonunun geri verdiği değere (değer hariç) kadar endekslenerek sütun (field) alan değerlerine erişim sağlanır.
Ayrıca, mysql_fetch_lengths() fonksiyonu ile sütun (field) değerlerinin uzunlukları elde edilebilir.
Dönüş değeri
Bir sonraki satır(row) için MYSQL_ROW yapı değerini, okunacak daha fazla satır değeri kalmadığında veya bir hata meydana geldiğinde NULL bir değer geri verir.
Hata durumu
mysql_fetch_row() fonksiyonunun kullanımları arasında hata durumu sıfırlanmaz.
CR_SERVER_LOST : Sorgulama esnasında sunucu bağlantısının kesildiğini gösterir.
CR_UNKNOWN_ERROR : Bilinmeyen bir hatayı gösterir.
Bir bağlantı üzerinde mysql_store_result(), mysql_use_result() veya mysql_list_dbs() fonksiyonları ile elde edilen ve result parametresi ile gösterilen veri (result set) için tahsis edilen belleği boşaltır.
Dönüş değeri
Yok.
Hata durumu
Yok.
mysql_real_connect() fonksiyonu için uygun bir MYSQL nesnesi tahsis eder. Eğer mysql parametresi NULL bir işaretçi ise, yeni bir nesne tahsis ederek geri verir. Aksi takdirde, nesneye ilk değer verilir ve adresi geri verilir. Eğer mysql_init() fonksiyonu yeni bir nesne tahsis ederse, bağlantıyı kapatmak üzere mysql_close() fonksiyonu çağrıldığında nesneye tahsisi edilen bellek boşaltılır.
Dönüş değeri
Bir MYSQL* handle değeri, yeni bir nesne tahsisi için yeterli bellek yoksa NULL bir değer geri verilir.
Hata durumu
Yetersiz bellek durumunda NULL bir değer geri verir.
mysql_store_result() veya mysql_use_result() fonksiyonları ile bir bağlantı üzerinden elde edilen bir sonuç setindeki sütunların (alan) sayısını geri verir. Bu fonksiyonlar NULL bir değer geri verdiğinde, MYSQL* parametresi ile çalışan mysql_field_count(MYSQL *mysql) fonksiyonu kullanılarak sütun sayısı elde edilebilir.
Dönüş değeri
Sonuç setindeki sütunların sayısını gösteren unsigned int bir değer geri verir.
Hata durumu
Yok.
stmt_str parametresi ile gçösterilen ve NULL bir değer ile sonlandırılmış karakter dizisinde yer alan SQL komutunu çalıştırır. Birden fazla komut çalıştırılması için komutların arasına noktalı virgül işareti (;) konulur.
Dönüş değeri
Komut başarıyla çalışırsa 0, bir hata meydana gelirse 0 olmayan bir değer geri verir.
Hata durumu
CR_COMMANDS_OUT_OF_SYNC : Komutların uygun olmayan sırada çalıştırıldığını gösterir.
CR_SERVER_GONE_ERROR : Sunucu irtibatının olmadığını gösterir.
CR_SERVER_LOST : Sorgulama esnasında sunucu irtibatının sona erdiğini gösterir.
CR_UNKNOWN_ERROR : Bilinmeyen bir hatayı gösterir.
Sunucu üzerinde çalışan MySQL veritabanına bir bağlantı oluşturur. Geçerli bir MYSQL bağlantısı kullanmaya gerek duyan diğer API fonksiyonlarını çalıştırmak için, mysql_real_connect() fonksiyonunun çalışmasını başarıyla sonuçlandırması gerekir.
Parametreler
MYSQL *mysql : Mevcut MYSQL yapısının adresini gösterir. MYSQL yapısını elde etmek için mysql_init() fonksiyonu kullanılır.
const char *host : Bu değer bir host adı (localhost gibi) veya bir IP adresi olabilir. Eğer, bu değer NULL veya "localhost" karakter dizisini içeriyorsa, yerel bir host'a bağlantı yapılır.
const char *user : Bu değer kullanıcının MySQL bağlantı kimliğini gösterir. NULL veya boş bir karakter dizisi ("") içerirse, aktif kullanıcı ifade edilir.
const char *passwd : Bir önceki parametrede gösterilen kullanıcı için tanımlanmış olan parolayı gösterir.
const char *db : Veritabanının adını gösterir. Eğer NULL değilse, bağlantı bu değeri ön tanımlı veritabanı olarak ayarlar.
unsigned int port : Eğer 0 değilse, bu değer TCP/IP bağlantısı için port numarası olarak kullanılır. host parametresi bağlantının türünü belirler.
const char *unix_socket : Eğer NULL değilse, bu karakter dizisi kullanılan soket veya named pipe'ı tanımlar.
unsigned long client_flag : Genellikle 0 değeri alır. Aşağıdaki değerlerin birleşiminden oluşabilir:
CLIENT_COMPRESS: Sıkıştırma protokolünü kullanır.
CLIENT_FOUND_ROWS: Değişen değil bulunan (koşulu sağlayan) satır sayısını geri verir.
CLIENT_IGNORE_SIGPIPE: Client kütüphanenin bir SIGPIPE signal handler kurmasını önler. Uygulama tarafından zaten kurulmuş olan bir handler ile çatışmayı önlemek için kullanılır.
CLIENT_IGNORE_SPACE: Fonksiyon isimlerinden sonra boşluk karakteri kullanılmasını sağlar. Tüm fonksiyon isimlerini ayrılmış olarak atar.
CLIENT_INTERACTIVE: Bağlantıyı kapatmadan önce, aktif olmayan süre için interactive_timeout (wait_timeout yerine) saniyelerin tanımlanmasına olanak sağlar. Client oturumunun wait_timeout değişkeni, oturumun interactive_timeout değişken değerine ayarlanır.
CLIENT_LOCAL_FILES: LOAD DATA LOCAL MySQL komutunun kullanılmasını sağlar.
CLIENT_MULTI_RESULTS: Sunucuya, Client'ın çoklu-komut uygulamalarından elde edilen sonuç setlerine işlem yapabileceğini gösterir. Eğer CLIENT_MULTI_STATEMENTS değeri devreye girerse, bu değer otomatik olarak devreye girer.
CLIENT_MULTI_STATEMENTS: Sunucuya, Client'ın tek bir karakter dizisi içinde noktalı virgül (;) ile ayrılmış çoklu komut gönderebileceğini gösterir. Eğer, bu değer devreye girmemişse, çoklu komut uygulaması gerçekleşmez.
CLIENT_NO_SCHEMA: db_name.tbl_name.col_name yazılım şekline izin vermez. Bu yazım şekli ODBC ile kullanılır. Bazı ODBC programlarında hatalara işlem yapmak için elverişli olan bu yazım şeklini kullanırsanız, bir hata meydana gelir.
CLIENT_ODBC: Kullanılmamaktadır.
CLIENT_SSL: SSL (kriptolu protokol) kullanır. Bu seçeneğe programlar tarafından işlem yapılmamalıdır. Client kütüphane içinde dahili olarak ayarlanır. Bu değer yerine, mysql_real_connect() fonksiyonunu çağırmadan önce mysql_ssl_set() fonksiyonunu kullanabilirsiniz.
CLIENT_REMEMBER_OPTIONS: mysql_options() fonksiyonuna yapılan çağrılar tarafından tanımlanır. Bu seçenek kullanılmadığında, eğer mysql_real_connect() fonksiyonu başarısızlığa uğrarsa, tekrar bağlantı yapmayı denemeden önce, mysql_options() fonksiyonunu tekrar çağırmanız gerekir. Bu seçenek tanımlandığında, mysql_options() fonksiyonunun tekrar çağrılmasına gerek kalmaz.
Dönüş değeri
Bağlantı başarılı olursa MYSQL* bağlantı handle değeri, aksi takdirde NULL bir değer geri verir. Başarılı bir bağlantı durumunda, dönüş değeri ilk parametre değeri ile aynıdır.
Hata durumu
CR_CONN_HOST_ERROR : MySQL sunucuya bağlantının başarısız olduğunu gösterir.
CR_CONNECTION_ERROR : Lokal MySQL sunucuya bağlantının başarısız olduğunu gösterir.
CR_IPSOCK_ERROR : Bir IP soket oluşturmada hata olduğunu gösterir.
CR_OUT_OF_MEMORY : Bellek yetersizliğini gösterir.
CR_SOCKET_CREATE_ERROR : Unix soketini oluşturmada hata olduğunu gösterir.
CR_UNKNOWN_HOST : Host adı için IP adresi bulmada başarısızlık olduğunu gösterir.
CR_VERSION_ERROR : Farklı bir protokol sürümü kullanan Client kütüphane ile sunucuya bağlanma denemesinde bir protokol uyumsuzluğu olduğunu gösterir.
CR_NAMEDPIPEOPEN_ERROR : Windows'ta Named Pipe oluşturmada başarısızlık olduğunu gösterir.
CR_NAMEDPIPEWAIT_ERROR : Windows'ta Named Pipe beklemede başarısızlık olduğunu gösterir.
CR_NAMEDPIPESETSTATE_ERROR : Windows'ta Named Pipe elde etmede başarısızlık olduğunu gösterir.
CR_SERVER_LOST : connect_timeout değeri 0'dan büyük olduğunda, sunucuya bağlanmanın bu değerden daha fazla zaman aldığını veya bağlanmaya çalışırken sunucunun devre dışı kaldığını gösterir.
mysql_query() veya mysql_real_query() fonksiyonlarından birisi çalıştırıldıktan sonra, bir sonuç seti oluşturan SELECT, SHOW, DESCRIBE, EXPLAIN, CHECK TABLE benzeri her komut için mysql_store_result() veya mysql_use_result() fonksiyonu çağrılır. Sonuç seti ile ilgili işlemler tamamlandıktan sonra, mysql_free_result() fonksiyonunu çağırmanız gerekir.
mysql_store_result() fonksiyonu bir sorgulama işlemi sonucunda elde edilen sonuç setinin tamamını Client'a aktarır. Bir MYSQL_RES yapısı tahsis eder ve sonuçları bu yapı içine yerleştirir.
Dönüş değeri
Başarılı olduğunda, sonuçları içeren bir MYSQL_RES yapısı, bir hata meydana geldiğinde ise NULL (0) bir değer geri verir.
Hata durumu
mysql_store_result() fonksiyonu başarılı olduğunda resets mysql_error() ve mysql_errno() fonksiyonlarını sıfırlar.
CR_COMMANDS_OUT_OF_SYNC : Komutların uygun olmayan sırada çalıştırıldığını gösterir.
CR_OUT_OF_MEMORY : Bellek yetersizliğini gösterir.
CR_SERVER_GONE_ERROR : MySQL sunucu irtibatının olmadığını gösterir.
CR_SERVER_LOST : Sorgulama esnasında sunucu irtibatının sona erdiğini gösterir.
CR_UNKNOWN_ERROR : Bilinmeyen bir hatayı gösterir.