SQLCopyDesc İşlevi

Uygunluk
Tanıtılan Sürüm: ODBC 3.0 Standartlarına Uyum: ISO 92

Özet
SQLCopyDesc, tanımlayıcı bilgisini bir tanımlayıcı tutamacından diğerine kopyalar.

Syntax

  
SQLRETURN SQLCopyDesc(  
     SQLHDESC     SourceDescHandle,  
     SQLHDESC     TargetDescHandle);  

Arguments

SourceDescHandle
[Giriş] Kaynak tanımlayıcı kullanıcı adı.

TargetDescHandle
[Giriş] Hedef tanımlayıcı kullanıcı adı. TargetDescHandle argümanı, bir uygulama tanımlayıcısına veya IPD'ye bir tutucu olabilir. TargetDescHandle IRD'ye bir tutamaya ayarlanamaz veya SQLCopyDesc SQLSTATE HY016 döndürür (Uygulama satır tanımlayıcısını değiştiremez).

İadeler

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR veya SQL_INVALID_HANDLE.

Diagnostics

SQLCopyDesc SQL_ERROR veya SQL_SUCCESS_WITH_INFO döndürdüğünde, ilişkili bir SQLSTATE değeri alınabilir; bu değer SQLGetDiagRec ile SQL_HANDLE_DESC HandleType ve TargetDescHandleHandle ile çağrılar. Çağrıda geçersiz bir SourceDescHandle ilettiyse, SQL_INVALID_HANDLE döner, ancak SQLSTATE geri dönmez. Aşağıdaki tablo, SQLCopyDesc tarafından sıkça duygulanan SQLSTATE değerlerini listeler ve her birini bu fonksiyon 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.

Hata dönerken, SQLCopyDesc çağrısı hemen iptal edilir ve TargetDescHandle tanımlayıcısındaki alanların içeriği tanımlanmamış olur.

SQLCopyDesc,SQLGetDescField ve SQLSetDescField çağrılarak uygulanabildiğinden, SQLCopyDescSQLGetDescField veya SQLSetDescField tarafından döndürülen SQLSTATE'leri döndürebilir.

Comments

SQLCopyDesc'e yapılan bir çağrı, kaynak tanımlayıcı kolunun alanlarını hedef tanımlayıcı tutamacına kopyalar. Alanlar yalnızca bir uygulama tanımlayıcısına veya IPD'ye kopyalanabilir, ancak IRD'ye kopyalanamaz. Alanlar bir uygulamadan veya uygulama tanımlayıcısından kopyalanabilir.

Alanlar, yalnızca ifade tutamacı hazırlanmış veya çalıştırılmış durumdaysa, IRD'den kopyalanabilir; aksi takdirde, fonksiyon SQLSTATE HY007 döndürür (Associated statement hazırlanmamıştır).

Alanlar, bir bildirim hazırlanmış olup olmamasına bakmaksızın IPD'den kopyalanabilir. Dinamik parametrelerle bir SQL ifadesi hazırlanmışsa ve IPD'nin otomatik popülasyonu desteklenip etkinleştirilmişse, IPD sürücü tarafından doldurulur. SQLCopyDesc çağrıldığında, IPD SourceDescHandle olarak çağrıldığında, doldurulmuş alanlar kopyalanır. IPD sürücü tarafından doldurulmazsa, IPD'deki alanların içeriği kopyalanır.

Tanımlayıcının tüm alanları, tanımlayıcı tutacağının otomatik mi yoksa açıkça mı tahsis edildiğini belirten SQL_DESC_ALLOC_TYPE hariç, alan hedef tanımlayıcı için tanımlanmış olup olmamasına bakmaksızın kopyalanır. Kopyalanan alanlar varolan alanların üzerine yazılır.

Sürücü, SourceDescHandle ve TargetDescHandle argümanları aynı sürücüyle ilişkilendiriliyorsa, sürücüler iki farklı bağlantı veya ortamda olsa bile tüm tanımlayıcı alanlarını kopyalar. SourceDescHandle ve TargetDescHandle argümanları farklı sürücülerle ilişkilendiriliyorsa, Driver Manager ODBC tanımlı alanları kopyalar, ancak sürücü tanımlı alanları veya tanımlayıcı türü için ODBC tarafından tanımlanmayan alanları kopyalamaz.

SQLCopyDesc çağrısı hata olursa hemen iptal edilir.

SQL_DESC_DATA_PTR alanı kopyalandığında, hedef tanımlayıcıda tutarlılık kontrolü yapılır. Tutarlılık kontrolü başarısız olursa, SQLSTATE HY021 (Tutarsız tanımlayıcı bilgisi) döner ve SQLCopyDesc çağrısı hemen iptal edilir. Tutarlılık kontrolleri hakkında daha fazla bilgi için SQLSetDescRec Fonksiyonu içindeki "Tutarlılık Kontrolleri"ne bakınız.

Tanımlayıcı tutamaçları, bağlantılar farklı ortamlarda olsa bile bağlantılar arasında kopyalanabilir. Sürücü Yöneticisi, kaynak ve hedef tanımlayıcı handle'ların aynı bağlantıya ait olmadığını ve iki bağlantının ayrı sürücülere ait olduğunu tespit ederse, SQLGetDescField ve SQLSetDescField kullanarak alan alan kopyalama gerçekleştirerek SQLCopyDesc'i uygular.

SQLCopyDesc, bir sürücüde SourceDescHandle ve başka bir sürücüde TargetDescHandle ile çağrıldığında, SourceDescHandle'ın hata kuyruğu temizlenir. Bunun nedeni, bu durumda SQLCopyDesc'inSQLGetDescField ve SQLSetDescField çağrılarıyla uygulanmasıdır.

Tanımlayıcı başlığı veya kayıttaki alanların tanımı için SQLSetDescField Fonksiyonu'na bakınız. Tanımlayıcılar hakkında daha fazla bilgi için bakınız: Tanımlayıcılar.

Tablolar Arasında Satırların Kopyalanması

Bir uygulama, verileri uygulama seviyesinde kopyalamadan bir tablodan diğerine kopyalayabilir. Bunu yapmak için uygulama, aynı veri tamponlarını ve tanımlayıcı bilgilerini, veriyi alan bir ifade ile veriyi bir kopyaya ekleyen ifadeye bağlar. Bu, bir uygulama tanımlayıcısını paylaşarak (açıkça tahsis edilen tanımlayıcıyı hem bir ifadeye ARD, hem de başka bir ifadede APD olarak bağlamak) veya SQLCopyDesc kullanılarak ARD ile APD arasındaki bağlamaları kopyalayarak gerçekleştirilebilir. Eğer deyimler farklı bağlantılardaysa, SQLCopyDesc kullanılmalıdır. Ayrıca, iki ibildirimin IRD ve IPD arasındaki bağlamalarını kopyalamak için SQLCopyDesc çağrılmalıdır. Aynı bağlantıdaki ifadeler arasında kopyalama yaparken, bu işlemin başarılı olması için sürücünün SQLGetInfo'ya yaptığı çağrı için geri dönen SQL_ACTIVE_STATEMENTS bilgi tipi 1'den büyük olmalıdır. (Bağlantılar arasında kopyalama yaparken durum böyle değildir.)

Kod Örneği

Aşağıdaki örnekte, tanımlayıcı işlemler kullanılarak PartsSource tablosunun alanları PartsCopy tablosuna kopyalanır. PartsSource tablosunun içeriği hstmt0'da satır kümesi tamponlarına alınır. Bu değerler, hstmt1 üzerindeki bir ifadenin INSERT parametreleri olarak PartsCopy tablosunun sütunlarını doldurmak için kullanılır. Bunu yapmak için, hstmt0'nın IRD'sinin alanları hstmt1'in IPD'sinin alanlarına kopyalanır ve hstmt0'nin ARD'sinin alanları hstmt1'in APD alanlarına kopyalanır. Çıkış parametreleri olan bir ifadeden giriş parametresi olan IPD alanlarına IRD alanlarını kopyaladığınızda, IPD'nin SQL_DESC_PARAMETER_TYPE özniteliğini SQL_PARAM_INPUT olarak ayarlamak için SQLSetDescField kullanın.

#define ROWS 100  
#define DESC_LEN 50  
#define SQL_SUCCEEDED(rc) (rc == SQL_SUCCESS || rc == SQL_SUCCESS_WITH_INFO)  
  
// Template for a row  
typedef struct {  
   SQLINTEGER   sPartID;  
   SQLINTEGER   cbPartID;  
   SQLUCHAR     szDescription[DESC_LENGTH];  
   SQLINTEGER   cbDescription;  
   REAL         sPrice;  
   SQLINTEGER   cbPrice;  
} PartsSource;  
  
PartsSource    rget[ROWS];          // rowset buffer  
SQLUSMALLINT   sts_ptr[ROWS];       // status pointer  
SQLHSTMT       hstmt0, hstmt1;  
SQLHDESC       hArd0, hIrd0, hApd1, hIpd1;  
  
// ARD and IRD of hstmt0  
SQLGetStmtAttr(hstmt0, SQL_ATTR_APP_ROW_DESC, &hArd0, 0, NULL);  
SQLGetStmtAttr(hstmt0, SQL_ATTR_IMP_ROW_DESC, &hIrd0, 0, NULL);  
  
// APD and IPD of hstmt1  
SQLGetStmtAttr(hstmt1, SQL_ATTR_APP_PARAM_DESC, &hApd1, 0, NULL);  
SQLGetStmtAttr(hstmt1, SQL_ATTR_IMP_PARAM_DESC, &hIpd1, 0, NULL);  
  
// Use row-wise binding on hstmt0 to fetch rows  
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_BIND_TYPE, (SQLPOINTER) sizeof(PartsSource), 0);  
  
// Set rowset size for hstmt0  
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_ARRAY_SIZE, (SQLPOINTER) ROWS, 0);  
  
// Execute a select statement  
SQLExecDirect(hstmt0, "SELECT PARTID, DESCRIPTION, PRICE FROM PARTS ORDER BY 3, 1, 2"",  
               SQL_NTS);  
  
// Bind  
SQLBindCol(hstmt0, 1, SQL_C_SLONG, rget[0].sPartID, 0,   
   &rget[0].cbPartID);  
SQLBindCol(hstmt0, 2, SQL_C_CHAR, &rget[0].szDescription, DESC_LEN,   
   &rget[0].cbDescription);  
SQLBindCol(hstmt0, 3, SQL_C_FLOAT, rget[0].sPrice,   
   0, &rget[0].cbPrice);  
  
// Perform parameter bindings on hstmt1.   
SQLCopyDesc(hArd0, hApd1);  
SQLCopyDesc(hIrd0, hIpd1);  
  
// Set the array status pointer of IRD  
SQLSetStmtAttr(hstmt0, SQL_ATTR_ROW_STATUS_PTR, sts_ptr, SQL_IS_POINTER);  
  
// Set the ARRAY_STATUS_PTR field of APD to be the same  
// as that in IRD.  
SQLSetStmtAttr(hstmt1, SQL_ATTR_PARAM_OPERATION_PTR, sts_ptr, SQL_IS_POINTER);  
  
// Set the hIpd1 records as input parameters  
rc = SQLSetDescField(hIpd1, 1, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);  
rc = SQLSetDescField(hIpd1, 2, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);  
rc = SQLSetDescField(hIpd1, 3, SQL_DESC_PARAMETER_TYPE, (SQLPOINTER)SQL_PARAM_INPUT, SQL_IS_INTEGER);  
  
// Prepare an insert statement on hstmt1. PartsCopy is a copy of  
// PartsSource  
SQLPrepare(hstmt1, "INSERT INTO PARTS_COPY VALUES (?, ?, ?)", SQL_NTS);  
  
// In a loop, fetch a rowset, and copy the fetched rowset to PARTS_COPY  
  
rc = SQLFetchScroll(hstmt0, SQL_FETCH_NEXT, 0);  
while (SQL_SUCCEEDED(rc)) {  
  
   // After the call to SQLFetchScroll, the status array has row   
   // statuses. This array is used as input status in the APD  
   // and hence determines which elements of the rowset buffer  
   // are inserted.  
   SQLExecute(hstmt1);  
  
   rc = SQLFetchScroll(hstmt0, SQL_FETCH_NEXT, 0);  
} // while  

İlgili Fonksiyonlar

Ayrıca Bkz.

ODBC API Referansı
ODBC Üst Bilgi Dosyaları