SQLBindCol İşlevi

Uygunluk
Kullanıma Sunulan Sürüm: ODBC 1.0 Standartları Uyumluluğu: ISO 92

Summary
SQLBindCol , uygulama veri tamponlarını sonuç kümesindeki sütunlara bağlar.

Syntax

  
SQLRETURN SQLBindCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

Arguments

StatementHandle
[Giriş] Deyim tanıtıcısı.

ColumnNumber
[Giriş] Bağlanacak sonuç kümesi sütununun sayısı. Sütunlar, 0'dan başlayarak artan sütun sırasına göre numaralandırılır; burada 0 numaralı sütun yer imimi sütunudur. Yer imleri kullanılmıyorsa - yani SQL_ATTR_USE_BOOKMARKS ifadesi özbeğinin SQL_UB_OFF olarak ayarlandığı - sütun numaraları 1'den başlar.

Targettype
[Giriş] *TargetValuePtr tamponunun C veri tipinin tanımlayıcısı. Veri kaynağından SQLFetch, SQLFetchScroll, SQLBulkOperations veya SQLSetPos ile veri alırken, sürücü veriyi bu tipe dönüştürür; Veri kaynağına SQLBulkOperations veya SQLSetPos ile gönderdiğinde, sürücü bu türden veriyi dönüştürür. Geçerli C veri tipleri ve tür tanımlayıcılarının listesi için, Ek D: Veri Tipleri'ndeki C Veri Tipleri bölümüne bakınız.

Eğer TargetType argümanı bir aralık veri tipi ise, ARD'nin SQL_DESC_DATETIME_INTERVAL_PRECISION ve SQL_DESC_PRECISION alanlarında sırasıyla belirlenen varsayılan aralık lider hassasiyeti (2) ve varsayılan aralık saniyesi hassasiyeti (6) veri için kullanılır. Eğer TargetType argümanı SQL_C_NUMERIC ise, ARD'nin SQL_DESC_PRECISION ve SQL_DESC_SCALE alanlarında belirlenen varsayılan hassasiyet (sürücü tarafından tanımlanmış) ve varsayılan ölçek (0) veri için kullanılır. Herhangi bir varsayılan hassasiyet veya ölçek uygun değilse, uygulama uygun tanımlayıcı alanını SQLSetDescField veya SQLSetDescRec çağrısıyla açıkça ayarlamalıdır.

Ayrıca genişletilmiş bir C veri tipi de belirtebilirsiniz. Daha fazla bilgi için bkz. ODBC'de C Veri Türleri.

TargetValuePtr
[Ertelenmiş Giriş/Çıkış] Veri tamponuna işaret ederek sütuna bağlanın. SQLFetch ve SQLFetchScroll bu tamponda veri döndürür. SQLBulkOperations , Operasyon SQL_FETCH_BY_BOOKMARK olduğunda bu tampondaki verileri döndürür; Operasyon SQL_ADD veya SQL_UPDATE_BY_BOOKMARK olduğunda bu tampondan veri alır. SQLSetPos,İşlem SQL_REFRESH olduğunda bu tampondaki veri döndürür; Operasyon SQL_UPDATE olduğunda bu tampondan veri alır.

Eğer TargetValuePtr bir null işaretçiyse, sürücü sütunun veri tamponunu kaldırır. Bir uygulama, SQL_UNBIND seçeneğiyle SQLFreeStmt'yi çağırarak tüm sütunları kaldırabilir. Bir uygulama, bir sütunun veri tamponunu kaldırabilir ancak yine de bir uzunluk/gösterge tamponu sınırına sahip olabilir; eğer SQLBindCol çağrısındaki TargetValuePtr argümanı bir null işaretçiyse ancak StrLen_or_IndPtr argüman geçerli bir değerse.

BufferLength
[Giriş] *TargetValuePtr tamponunun bayt cinsinden uzunluğu.

Sürücü, değişken uzunlukta verileri, örneğin karakter veya ikili veri döndürdüğünde, *TargetValuePtr buffer'ının sonundan geçtiğini önlemek için BufferLength kullanır. Sürücünün *TargetValuePtr'e karakter verisi döndürdüğünde null-sonlandırma karakterini saydığını unutmayın. *Bu nedenle TargetValuePtr, null-sonlandırma karakteri için boşluk içermelidir, aksi takdirde sürücü veriyi kıstırır.

Sürücü sabit uzunluklu verileri, örneğin tam sayı veya tarih yapısı döndürdüğünde, sürücü BufferLength'i görmezden gelir ve tamponun veriyi tutacak kadar büyük olduğunu varsayar. Bu nedenle, uygulamanın sabit uzunluklu veri için yeterince büyük bir tampon ayırması önemlidir, aksi takdirde sürücü tamponun sonundan daha fazla yazar.

SQLBindCol , BufferLength 0'dan küçük olduğunda SQLSTATE HY090 (Geçersiz dizi veya tampon uzunluğu) döndürür, ancak BufferLength 0 olduğunda döndürmez. Ancak , TargetType bir karakter türü belirlerse, bir uygulama BufferLength'ü 0'a ayarlamamalıdır, çünkü ISO CLI uyumlu sürücüler bu durumda SQLSTATE HY090 (Geçersiz dizi veya tampon uzunluğu) döndürür.

StrLen_or_IndPtr
[Ertelenmiş Giriş/Çıkış] Uzunluk/gösterge tamponu için işaret yaparak sütuna bağlanın. SQLFetch ve SQLFetchScroll bu tamponda bir değer döndürür. SQLBulkOperations , Operation SQL_ADD, SQL_UPDATE_BY_BOOKMARK veya SQL_DELETE_BY_BOOKMARK olduğunda bu tampondan bir değer alır. SQLBulkOperations , Operation SQL_FETCH_BY_BOOKMARK olduğunda bu buffer'da bir değer döndürür. SQLSetPos,Operasyon SQL_REFRESH olduğunda bu tamponda bir değer döndürür; Operasyon SQL_UPDATE olduğunda bu tampondan bir değer alır.

SQLFetch, SQLFetchScroll, SQLBulkOperations ve SQLSetPos uzunluk/gösterge tamponu içinde aşağıdaki değerleri döndürebilir:

• Geri dönebilecek verinin uzunluğu

• SQL_NO_TOTAL

• SQL_NULL_DATA

Uygulama, SQLBulkOperations veya SQLSetPos ile kullanılmak üzere uzunluk/gösterge tamponuna aşağıdaki değerleri koyabilir:

• Gönderilen verinin uzunluğu

• SQL_NTS

• SQL_NULL_DATA

• SQL_DATA_AT_EXEC

• SQL_LEN_DATA_AT_EXEC makrosunun sonucu

• SQL_COLUMN_IGNORE

Eğer gösterge tamponu ve uzunluk tamponu ayrı tamponlar ise, gösterge tamponu yalnızca SQL_NULL_DATA döndürebilirken, uzunluk tamponu diğer tüm değerleri döndürebilir.

Daha fazla bilgi için SQLBulkOperations Function, SQLFetch Function, SQLSetPos Function ve Using Length/Indicator Values bölümlerine bakınız.

Eğer StrLen_or_IndPtr bir null işaretçiyse, uzunluk veya gösterge değeri kullanılmaz. Bu, veri getirirken bir hatadır ve veri NULL olur.

Uygulamanızın 64-bit işletim sisteminde çalışıp çalışmayacağı için ODBC 64-Bit Bilgileri'ne bakınız.

İadeler

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR veya SQL_INVALID_HANDLE.

Diagnostics

SQLBindCol SQL_ERROR veya SQL_SUCCESS_WITH_INFO döndürdüğünde, ilişkili bir SQLSTATE değeri alınabilir; bu değer SQLGetDiagRec çağrılarak SQL_HANDLE_STMT HandleType ve HandleType of StatementHandle ile elde edilebilir. Aşağıdaki tablo, genellikle SQLBindCol tarafından duygulanan SQLSTATE değerlerini listeler ve her birini bu fonksiyonun bağlamında açıklar; "(DM)" gösterimi, Sürücü Yöneticisi tarafından döndürülen SQLSTATE açıklamalarından önce gelir. Aksi belirtilmediği sürece, her SQLSTATE değeriyle ilişkili dönüş kodu SQL_ERROR.

SQLSTATE	Error	Description
01000	Genel uyarı	Sürücüye özgü bilgilendirici ileti. (İşlev SQL_SUCCESS_WITH_INFO döndürür.)
07006	Kısıtlanmış veri türü özniteliği ihlali	(DM) ColumnNumber argümanı 0 idi ve TargetType argümanı SQL_C_BOOKMARK veya SQL_C_VARBOOKMARK değildi.
07009	Geçersiz tanımlayıcı indeksi	ColumnNumber argümanı için belirtilen değer, sonuç kümesindeki maksimum sütun sayısını aşmıştır.
HY000	Genel hata	Belirli bir SQLSTATE olmayan ve uygulamaya özgü SQLSTATE tanımlanmayan bir hata oluştu. *MessageText arabelleğinde SQLGetDiagRec tarafından döndürülen hata iletisi, hatayı ve nedenini açıklar.
HY001	Bellek ayırma hatası	Sürücü, işlevin yürütülmesini veya tamamlanmasını desteklemek için gereken belleği ayıramadı.
HY003	Geçersiz uygulama tamponu türü	TargetType argümanı ne geçerli bir veri tipi ne de SQL_C_DEFAULT idi.
HY010	İşlev dizisi hatası	(DM) StatementHandle ile ilişkili bağlantı tanıtıcısı için zaman uyumsuz olarak yürütülen bir işlev çağrıldı. Bu asenkron fonksiyon SQLBindCol çağrıldığında hâlâ çalışıyordu. (DM) SQLExecute, SQLExecDirect veya SQLMoreResults, StatementHandle için çağrıldı ve SQL_PARAM_DATA_AVAILABLE döndürdü. Bu işlev, tüm akış parametreleri için veri alınmadan önce çağrıldı. (DM) StatementHandle için asenkron olarak çalışan bir fonksiyon çağrıldı ve bu fonksiyon çağrıldığında hâlâ çalışıyordu. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations veya SQLSetPos, StatementHandle için çağrıldı ve SQL_NEED_DATA döndürdü. Bu işlev, tüm yürütme sırasında veri parametreleri veya sütunları için veri gönderilmeden önce çağrıldı.
HY013	Bellek yönetimi hatası	Büyük olasılıkla düşük bellek koşulları nedeniyle, temel alınan bellek nesnelerine erişilemediğinden işlev çağrısı işlenemedi.
HY090	Geçersiz dize veya arabellek uzunluğu	(DM) BufferLength argümanı için belirtilen değer 0'dan küçüktü. (DM) Şoför ODBC 2'ydi. x sürücüsü olduğunda, ColumnNumber argümanı 0 olarak ayarlandı ve BufferLength argümanı için belirtilen değer 4'e eşit değildi.
HY117	Bilinmeyen işlem durumu nedeniyle bağlantı askıya alındı. Yalnızca bağlantıyı kesme ve salt okunur işlevlere izin verilir.	(DM) Askıya alınma durumu hakkında daha fazla bilgi için bkz. SQLEndTran İşlevi.
HYC00	İsteğe bağlı özellik uygulanmadı	Sürücü veya veri kaynağı, TargetType argümanı ile ilgili sütunun sürücüye özgü SQL veri tipinin birleşimiyle belirlenen dönüşümü desteklemez. Argüman ColumnNumber 0'dı ve sürücü yer imlerini desteklemiyor. Sürücü sadece ODBC 2'yi destekliyor. x ve TargetType argümanı aşağıdakilerden biriydi: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT ve Ek D: Veri Tipleri'ndeki C Veri Tipleri'nde listelenen aralık C veri tiplerinden herhangi biri. Sürücü yalnızca 3.50 öncesi ODBC sürümlerini destekliyor ve TargetType argümanı SQL_C_GUID.
HYT01	Bağlantı zaman aşımı süresi doldu	Veri kaynağı isteği yanıtlamadan önce bağlantı zaman aşımı süresi doldu. Bağlantı zaman aşımı süresi SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT aracılığıyla ayarlanır.
IM001	Sürücü bu işlevi desteklemiyor	(DM) StatementHandle ile ilişkili sürücü işlevi desteklemiyor.

Comments

SQLBindCol, sonuç kümesindeki sütunları uygulamadaki veri tamponları ve uzunluk/gösterge tamponlarına bağlamak için kullanılır. Uygulama verileri almak için SQLFetch, SQLFetchScroll veya SQLSetPos'u çağırdığında, sürücü belirlenen tamponlar içindeki bağlı sütunlar için verileri döndürür; daha fazla bilgi için SQLFetch Fonksiyonu bölümüne bakınız. Uygulama bir satırı güncellemek veya eklemek için SQLBulkOperations veya satırı güncellemek için SQLSetPos çağırdığında, sürücü belirlenen tamponlardan bağlı sütunlar için verileri alır; daha fazla bilgi için SQLBulkOperations Function veya SQLSetPos Fonksiyonu sayfasına bakınız. Bağlama hakkında daha fazla bilgi için Sonuçları Almak (Temel) bölümüne bakınız.

Sütunların verileri almak için bağlı olması gerekmemektedir. Bir uygulama ayrıca sütunlardan veri almak için SQLGetData çağırabilir. Bazı sütunları sıraya bağlamak ve diğerleri için SQLGetData çağrısı mümkün olsa da, bu bazı kısıtlamalara tabi olabilir. Daha fazla bilgi için SQLGetData'ya bakınız.

Bağlama, Çözme ve Yeniden Bağlama Kolonları

Bir sütun, sonuç kümesinden veri alındıktan sonra bile herhangi bir zamanda bağlanabilir, sınırsız veya geri dönüşebilir. Yeni bağlama, bir sonraki bağlama fonksiyonu çağrıldığında etkilenir. Örneğin, bir uygulamanın bir sonuç kümesindeki sütunları bağladığını ve SQLFetch'i çağırdığını varsayalım. Sürücü, bağlı tamponlar içindeki verileri döndürür. Şimdi diyelim ki uygulama sütunları farklı bir tampon kümesine bağlıyor. Sürücü, yeni bağlanmış tamponlara yeni alınan satırın verilerini koymaz. Bunun yerine, SQLFetch tekrar çağrılana kadar bekler ve ardından bir sonraki satır için veriyi yeni bağlanmış tamponlara yerleştirir.

Note

Bir sütunu 0 sütuna bağlamadan önce her zaman ifade özniteliği SQL_ATTR_USE_BOOKMARKS ayarlanmalıdır. Bu zorunlu değildir ancak şiddetle tavsiye edilir.

Sütunları Bağlama

Bir sütunu bağlamak için bir uygulama SQLBindCol çağırır ve veri tamponunun sütun numarasını, türünü, adresini ve uzunluğunu, ayrıca uzunluk/gösterge tamponu adresini iletir. Bu adreslerin nasıl kullanıldığına dair bilgi için, bu bölümün ilerleyen bölümlerinde "Buffer Addresses" bölümüne bakınız. Bağlama sütunları hakkında daha fazla bilgi için bkz. Using SQLBindCol.

Bu tamponların kullanımı ertelenmiştir; yani, uygulama onları SQLBindCol'da bağlar, ancak sürücü diğer fonksiyonlardan - yani SQLBulkOperations, SQLFetch, SQLFetchScroll veya SQLSetPos'tan erişir. Uygulamanın sorumluluğu, bağlama yürürlüğe devam ettiği sürece SQLBindCol'da belirtilen işaretlerin geçerli kalmasını sağlamaktır. Uygulama bu işaretçilerin geçersiz hale gelmesine izin verirse - örneğin bir tamponu serbest bırakır - ve ardından geçerli olmasını bekleyen bir fonksiyon çağırırsa, sonuçlar tanımlanmaz. Daha fazla bilgi için bkz. Ertelenmiş Tamponlar.

Bağlama, yeni bir bağlama ile değiştirilere, sütun bağlanmadan açılana veya ifade serbest bırakılana kadar geçerlidir.

Sütunların Çözülmesi

Tek bir sütunu bağlamayı kaldırmak için, bir uygulama SQLBindCol'u çağırır; ColumnNumber o sütunun numarasına ayarlanmış ve TargetValuePtr sıfır işaretçiye ayarlanmıştır. ColumnNumber bağlanmamış bir sütuna atıfta bulunursa, SQLBindCol yine SQL_SUCCESS döndürür.

Tüm sütunları bağlamayı kaldırmak için, bir uygulama fOption SQL_UNBIND olarak ayarlanmış SQLFreeStmt çağırır. Bu, ARD'nin SQL_DESC_COUNT alanını sıfıra ayarlayarak da gerçekleştirilebilir.

Yeniden Bağlanan Sütunlar

Bir uygulama, bir bağlamayı değiştirmek için iki işlemden birini gerçekleştirebilir:

• Zaten bağlı olan bir sütun için yeni bir bağlama belirtmek üzere SQLBindCol çağırın. Sürücü, eski bağlamayı yenisiyle üzerine yazar.

• SQLBindCol'a bağlanma çağrısıyla belirtilen buffer adresine eklenecek bir ofset belirtin. Daha fazla bilgi için bir sonraki bölüm olan "Bağlanma Ofsetleri"ne bakınız.

Bağlama Ofsetleri

Bağlama ofseti, veri ve uzunluk/gösterge tamponlarının adreslerine ( TargetValuePtr ve StrLen_or_IndPtr argümanında belirtildiği gibi) denreference edilmeden önce eklenen bir değerdir. Ofsetler kullanıldığında, bağlamalar uygulamanın tamponlarının nasıl yerleştirildiğine dair bir "şablon" olur ve uygulama bu "şablonu" ofseti değiştirerek belleğin farklı alanlarına taşıyabilir. Her bağlamada her adrese aynı ofset eklendiği için, farklı sütunlar için tamponlar arasındaki göreceli kaymaların her tampon kümesi içinde aynı olması gerekir. Bu her zaman sıralı ciltleme kullanılırken geçerlidir; Uygulama, sütun bazında bağlanma kullanıldığında bunun doğru olması için tamponlarını dikkatlice yerleştirmelidir.

Bağlama ofseti kullanmak, temelde SQLBindCol çağrısı yoluyla bir sütunu yeniden bağlamanın etkisine sahiptir. Fark şu ki, SQLBindCol'a yapılan yeni bir çağrı veri tamponu ve uzunluk/gösterge tamponu için yeni adresler belirlerken, bağlama ofseti adresleri değiştirmez, sadece bir ofset ekler. Uygulama istediği zaman yeni bir ofset belirtebilir ve bu ofset her zaman orijinal bağlı adreslere eklenir. Özellikle, ofset 0 olarak ayarlanmışsa veya ifade özniteliği null işaretçiye ayarlanmışsa, sürücü orijinal sınırlı adresleri kullanır.

Bağlama ofseti belirtmek için uygulama, SQL_ATTR_ROW_BIND_OFFSET_PTR ifadesi niteliğini bir SQLINTEGER tampon adresine ayarlar. Uygulama, bağlayıcı kullanan bir fonksiyonu çağırmadan önce, bu tamponda bayt cinsinden bir ofset koyar. Kullanılacak tampon adresini belirlemek için sürücü, bağlamadaki adrese ofseti ekler. Adres ve ofsetin toplamı geçerli bir adres olmalıdır, ancak ofsetin eklendiği adresin geçerli olması gerekmez. Bağlama ofsetlerinin nasıl kullanıldığına dair daha fazla bilgi için bu bölümün ilerleyen bölümlerinde "Buffer Adresleri" bölümüne bakınız.

Bağlama Dizileri

Eğer SQL_ATTR_ROW_ARRAY_SIZE ifadesi özniteliğinin değeri olan satır kümesi büyüklüğü 1'den büyükse, uygulama tek tampon yerine tampon dizilerini bağlar. Daha fazla bilgi için Block Cursors sayfasına bakınız.

Uygulama dizileri iki şekilde bağlayabilir:

• Her sütuna bir dizi bağlayın. Bu, her veri yapısı (dizi) tek bir sütun için veri içerdiği için sütunlu bağlama olarak adlandırılır.

• Tüm bir satırın veriyi tutacak bir yapı tanımlayın ve bu yapılardan oluşan bir diziyi bağlayın. Bu, her veri yapısı tek bir satırın verisini içerdiği için satıra bağlı bağlanma olarak adlandırılır.

Her tampon dizisi, en az sıra kümesinin boyutu kadar çok eleman içermelidir.

Note

Bir uygulama, hizalanmanın geçerli olduğunu doğrulamalıdır. Hizalama konuları hakkında daha fazla bilgi için bkz. Hizalama.

Column-Wise Bağlama

Sütun bazında bağlamada, uygulama her sütuna ayrı veri ve uzunluk/gösterge dizilerini bağlar.

Sütun bazında bağlama kullanmak için uygulama önce SQL_ATTR_ROW_BIND_TYPE ifadesi niteliğini SQL_BIND_BY_COLUMN olarak ayarlar. (Bu varsayılan durumdur.) Her sütunun bağlanması için uygulama aşağıdaki adımları gerçekleştirir:

1. Bir veri tamponu dizisi tahsis eder.

2. Uzunluk/gösterge tamponları dizisi tahsis eder.

   Note

   Uygulama sütun-bazında bağlanma kullanılırken doğrudan tanımlayıcılara yazarsa, uzunluk ve gösterge verileri için ayrı dizilerle kullanılabilir.

3. SQLBindCol'u aşağıdaki argümanlarla çağırır:

   • TargetType , veri tamponu dizisinde tek bir elemanın türüdür.

   • TargetValuePtr, veri tamponu dizisi adresidir.

   • BufferLength , veri tamponu dizisinde tek bir elemanın boyutudur. BufferLength argümanı, veri sabit uzunlukta verisi olduğunda göz ardı edilir.

   • StrLen_or_IndPtr , uzunluk/gösterge dizisi adresidir.

Bu bilgilerin nasıl kullanıldığına dair daha fazla bilgi için, bu bölümün ilerleyen bölümlerinde "Buffer Adresleri" bölümüne bakınız. Sütunlu ciltleme hakkında daha fazla bilgi için bkz.Column-Wise Bağlama.

Row-Wise Bağlama

Satır bazında bağlamada, uygulama her sütun için veri ve uzunluk/gösterge tamponlarını içeren bir yapı tanımlar.

Satır bazında bağlama kullanmak için uygulama aşağıdaki adımları gerçekleştirir:

1. Tek bir veri satırını (hem veri hem de uzunluk/gösterge tamponları dahil) tutacak bir yapı tanımlar ve bu yapılardan oluşan bir diziyi tahsis eder.

   Note

   Eğer uygulama doğrudan tanımlayıcılara yazarsa sıralı bağlama kullanılırsa, uzunluk ve gösterge verileri için ayrı alanlar kullanılabilir.

2. SQL_ATTR_ROW_BIND_TYPE ifadesi özniteliğini, tek bir veri satırını içeren yapının büyüklüğüne veya sonuç sütunlarının bağlanacağı bir tampon örneğinin boyutuna ayarlar. Uzunluk, tüm bağlı sütunlar için alan ve yapının veya tamponun herhangi bir dolgusunu içermelidir; böylece bağlı sütunun adresi belirlenen uzunlukla artırıldığında, sonuç aynı sütunun bir sonraki satırdaki başlangıcına işaret edecektir. ANSI C'de sizeof operatörü kullanıldığında bu davranış garanti edilir.

3. Her sütunun bağlanması için aşağıdaki argümanlarla SQLBindCol çağırır:

   • TargetType , veri tamponu üyesinin sütuna bağlanacak türüdür.

   • TargetValuePtr, ilk dizi öğesindeki veri tamponu üyesinin adresidir.

   • BufferLength , veri tamponu üyesinin boyutudur.

   • StrLen_or_IndPtr , bağlanacak uzunluk/gösterge üyesinin adresidir.

Bu bilgilerin nasıl kullanıldığına dair daha fazla bilgi için, bu bölümün ilerleyen bölümlerinde "Buffer Adresleri" bölümüne bakınız. Sütunlu ciltleme hakkında daha fazla bilgi için bkz.Row-Wise Bağlama.

Tampon Adresleri

Buffer adresi, verinin gerçek adresi veya uzunluk/gösterge tamponudur. Sürücü, tampon adresini yazmadan hemen önce hesaplar (örneğin getirme zamanında). Aşağıdaki formülden hesaplanır; bu formül TargetValuePtr ve StrLen_or_IndPtr argümanlarında belirtilen adresler, bağlama ofseti ve satır numarası kullanılır:

Bağlı Adres + Bağlama Ofseti + ((Sıra Numarası - 1) x Eleman Boyutu)

burada formülün değişkenleri aşağıdaki tabloda açıklandığı gibi tanımlanır.

Variable	Description
Bağlı Adres	Veri tamponları için, SQLBindCol'dakiTargetValuePtr argümanıyla belirtilen adres. Uzunluk/gösterge tamponları için, SQLBindCol'daStrLen_or_IndPtr argümanı ile belirtilen adres. Daha fazla bilgi için, "Descriptors and SQLBindCol" bölümündeki "Ek Yorumlar" bölümüne bakınız. Sınır adresi 0 ise, önceki formülle hesaplanan adres sıfır değilse bile veri değeri döndürülmez.
Bağlama Ofseti	Eğer satır-bazı bağlama kullanılırsa, SQL_ATTR_ROW_BIND_OFFSET_PTR ifadesi özniteliğiyle belirtilen adreste saklanan değer. Eğer sütun bazında bağlama kullanılırsa veya SQL_ATTR_ROW_BIND_OFFSET_PTR ifadesi özniteliğinin değeri null işaretçiyse, Bağlama Ofseti 0'dır.
Sıra Numarası	Sıra kümesindeki sıranın 1 bazlı sayısı. Varsayılan tek satırlı getirmeler için bu 1'dir.
Element Boyutu	Bağlı dizideki bir elemanın boyutu. Sütun bazında bağlama kullanılırsa, uzunluk/gösterge tamponları için sizeof (SQLINTEGER ) kullanılır. Veri tamponları için, veri tipi değişken uzunlukta ise, SQLBindCol'dakiBufferLength argümanının değeri, veri tipi sabit uzunlukta ise veri tipinin boyutudur. Eğer satır bazında bağlama kullanılırsa, bu hem veri hem de uzunluk/gösterge tamponları için SQL_ATTR_ROW_BIND_TYPE ifadesi özniteliğinin değeridir.

Descriptors ve SQLBindCol

Aşağıdaki bölümler, SQLBindCol'un tanımlayıcılarla nasıl etkileşime girdiğini açıklar.

Caution

Bir ifade için SQLBindCol çağırmak diğer ifadeleri etkileyebilir. Bu, ifadeyle ilişkili ARD açıkça tahsis edildiğinde ve diğer ifadelerle de ilişkilendirildiğinde gerçekleşir. SQLBindCol tanımlayıcıyı değiştirdiğinden, bu değişiklikler bu tanımlayıcıyla ilişkilendirilen tüm ilemlere uygulanır. Eğer bu gerekli davranış değilse, uygulama SQLBindCol'u çağırmadan önce bu tanımlayıcıyı diğer i'mlerden ayırmalıdır.

Argüman Haritaları

Kavramsal olarak, SQLBindCol aşağıdaki adımları sırayla gerçekleştirir:

1. ARD tutamacını elde etmek için SQLGetStmtAttr çağırır.

2. Bu tanımlayıcının SQL_DESC_COUNT alanını almak için SQLGetDescField çağırır ve ColumnNumber argümanındaki değer SQL_DESC_COUNT değerini aşarsa, SQLSetDescField çağırarak SQL_DESC_COUNT değerini ColumnNumber'a çıkarır.

3. SQLSetDescField'ı birden fazla kez çağırarak ARD'nin aşağıdaki alanlarına değerler atar:

   • TargetType değerine SQL_DESC_TYPE ve SQL_DESC_CONCISE_TYPE ayarlar, ancak TargetType bir tarih veya aralık alt tipinin kısa tanımlayıcılarından biri ise, SQL_DESC_TYPE'i sırasıyla SQL_DATETIME veya SQL_INTERVAL olarak ayarlar; SQL_DESC_CONCISE_TYPE kısa tanımlayıcıya ayar; ve SQL_DESC_DATETIME_INTERVAL_CODE ilgili tarih saati veya aralık alt koduna ayarlar.

   • TargetType için uygun şekilde bir veya daha fazla SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE ve SQL_DESC_DATETIME_INTERVAL_PRECISION ayarlar.

   • SQL_DESC_OCTET_LENGTH alanını BufferLength değerine ayarlar.

   • SQL_DESC_DATA_PTR alanını TargetValuePtr değerine ayarlar.

   • SQL_DESC_INDICATOR_PTR alanını StrLen_or_IndPtr değerine ayarlar. (Aşağıdaki paragrafa bakınız.)

   • SQL_DESC_OCTET_LENGTH_PTR alanını StrLen_or_IndPtr değerine ayar. (Aşağıdaki paragrafa bakınız.)

StrLen_or_IndPtr argümanının atıfta bulunduğu değişken hem gösterge hem de uzunluk bilgisi için kullanılır. Bir fetch sütun için bir null değerle karşılaşırsa, bu değişkende SQL_NULL_DATA saklar; aksi takdirde, veri uzunluğunu bu değişkende saklar. Bir null işaretçiyi StrLen_or_IndPtr olarak geçirmek, getirme işleminin veri uzunluğunu geri vermesini engeller ancak null bir değerle karşılaşırsa ve SQL_NULL_DATA geri getirme imkânı yoksa, getirme başarısız olur.

SQLBindCol çağrısı başarısız olursa, ARD'de belirleyeceği tanımlayıcı alanların içeriği tanımlanmamış olur ve ARD'nin SQL_DESC_COUNT alanının değeri değişmez.

COUNT Alanının örtük sıfırlanması

SQLBindCol , SQL_DESC_COUNT'yi yalnızca ColumnNumber argümanının değerine ayar, ancak bu değer SQL_DESC_COUNT değerini artıracaksa. TargetValuePtr argümanındaki değer bir null işaretçiyse ve ColumnNumber argümanındaki değer SQL_DESC_COUNT'e eşitse (yani en yüksek sınır sütunu bağlandığında), SQL_DESC_COUNT kalan en yüksek sınırlı sütunun sayısına ayarlanır.

SQL_DEFAULT Hakkında Uyarılar

Başarılı bir şekilde sütun verisini almak için uygulama, uygulama tamponunda verinin uzunluğunu ve başlangıç noktasını doğru şekilde belirlemelidir. Uygulama açık bir TargetType belirttiğinde, uygulama yanlış anlamaları kolayca tespit edilir. Ancak, uygulama bir SQL_DEFAULT Hedeftipi belirlediğinde, SQLBindCol , uygulamanın amaçladığı veri türünden farklı bir veri tipine sahip bir sütuna uygulanabilir; bu sütun, meta veride yapılan değişikliklerden veya kodun farklı bir sütuna uygulanmasıyla gerçekleşir. Bu durumda, uygulama her zaman getirilen sütun verisinin başlangıcını veya uzunluğunu belirleyemeyebilir. Bu, bildirilmeyen veri hatalarına veya bellek ihlallerine yol açabilir.

Kod Örneği

Aşağıdaki örnekte, bir uygulama Müşteriler tablosunda bir SELECT ifadesi çalıştırarak isimlere göre sıralanmış müşteri kimlikleri, isimleri ve telefon numaralarından oluşan bir sonuç setini döndürür. Daha sonra SQLBindCol'u çağırarak veri sütunlarını yerel tamponlara bağlar. Son olarak, uygulama her veri satırını SQLFetch ile alır ve her müşterinin adını, kimliğini ve telefon numarasını yazdırır.

Daha fazla kod örneği için SQLBulkOperations Function, SQLColumns Function, SQLFetchScroll Function ve SQLSetPos Function sayfalarına bakınız.

// SQLBindCol_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <stdio.h>  
  
#define UNICODE  
#include <sqlext.h>  
  
#define NAME_LEN 50  
#define PHONE_LEN 60
  
void show_error() {  
   printf("error\n");  
}  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
   SQLWCHAR szName[NAME_LEN], szPhone[PHONE_LEN], sCustID[NAME_LEN];  
   SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLWCHAR*) L"NorthWind", SQL_NTS, (SQLWCHAR*) NULL, 0, NULL, 0);  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {   
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               retcode = SQLExecDirect(hstmt, (SQLWCHAR *) L"SELECT CustomerID, ContactName, Phone FROM CUSTOMERS ORDER BY 2, 1, 3", SQL_NTS);  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
                  // Bind columns 1, 2, and 3  
                  retcode = SQLBindCol(hstmt, 1, SQL_C_WCHAR, &sCustID, 100, &cbCustID);  
                  retcode = SQLBindCol(hstmt, 2, SQL_C_WCHAR, szName, NAME_LEN, &cbName);  
                  retcode = SQLBindCol(hstmt, 3, SQL_C_WCHAR, szPhone, PHONE_LEN, &cbPhone);   
  
                  // Fetch and print each row of data. On an error, display a message and exit.  
                  for (int i=0 ; ; i++) {  
                     retcode = SQLFetch(hstmt);  
                     if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
                        show_error();  
                     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                     {
                        //replace wprintf with printf
                        //%S with %ls
                        //warning C4477: 'wprintf' : format string '%S' requires an argument of type 'char *'
                        //but variadic argument 2 has type 'SQLWCHAR *'
                        //wprintf(L"%d: %S %S %S\n", i + 1, sCustID, szName, szPhone);  
                        printf("%d: %ls %ls %ls\n", i + 1, sCustID, szName, szPhone);  
                    }    
                     else  
                        break;  
                  }  
               }  
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLCancel(hstmt);  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

Ayrıca bkz. Örnek ODBC Programı.

İlgili Fonksiyonlar

Hakkında bilgi için	Bkz:
Sonuç kümesindeki bir sütunla ilgili bilgi döndürme	SQLDescribeCol Fonksiyonu
Veri bloğunu getirme veya sonuç kümesinde kaydırma	SQLFetchScroll İşlevi
Birden çok veri satırı getirme	SQLFetch İşlevi
Sütun tamponlarının serbest bırakılması	SQLFreeStmt İşlevi
Veri sütununun bir bölümünü veya tamamını getirme	SQLGetData İşlevi
Sonuç kümesi sütunlarının sayısını döndürmek	SQLNumResultCols Fonksiyonu

İlgili içerik

• ODBC API referansı
• ODBC Üst Bilgi Dosyaları