SQLCopyDesc függvény

Megfelelőség
Bemutatott verzió: ODBC 3.0 szabványoknak megfelelés: ISO 92

Összefoglalás
SQLCopyDesc lemásolja a leíró információkat egyik leíró handle-ről a másikra.

Syntax

  
SQLRETURN SQLCopyDesc(  
     SQLHDESC     SourceDescHandle,  
     SQLHDESC     TargetDescHandle);  

Arguments

SourceDescHandle
[Bemenet] Forrásleíró kilincs.

TargetDescHandle
[Bemenet] Célleíró név. A TargetDescHandle érve lehet egy alkalmazásleíró vagy IPD fogantyúja. A TargetDescHandle nem állítható be IRD kezelőre, különben az SQLCopyDesc visszaadja az SQLSTATE HY016-ot (nem lehet módosítani implementációs sorleírást).

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR vagy SQL_INVALID_HANDLE.

Diagnostics

Amikor az SQLCopyDesc SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_DESC HandleType és egy TargetDescHandleHandle nevű HandleType (HandleType volt). Ha a hívásban egy érvénytelen SourceDescHandle került át, SQL_INVALID_HANDLE visszakerül, de nem tér vissza SQLSTATE-et. Az alábbi táblázat felsorolja az SQLCopyDesc által gyakran visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

Ha hiba jelenik meg, az SQLCopyDesc hívása azonnal megszakításra kerül, és a TargetDescHandle leírás mezői nem definiálódnak.

Mivel az SQLCopyDesc megvalósítható SQLGetDescField és SQLSetDescField hívásával, az SQLCopyDesc visszaadhatja az SQLGetDescField vagy SQLSetDescField által visszaadott SQLSTATE-eket.

Comments

Az SQLCopyDesc-hez való hívás a forrásleíró handle mezőit másolja a célleíró fogantyúra. A mezők csak alkalmazásleíróba vagy IPD-be másolhatók, IRD-be azonban nem. A mezők másolhatók alkalmazásból vagy implementációs leírásból.

A mezők csak akkor másolhatók az IRD-ről, ha a kijelentés handle előkészített vagy végrehajtott állapotban van; különben a függvény visszaadja az SQLSTATE HY007-et (Kapcsolódó utasítás nincs előkészítve).

A mezők lemásolhatók egy IPD-ből, függetlenül attól, hogy kijelentést készítettek vagy sem. Ha egy SQL utasítást készítettek dinamikus paraméterekkel, és az IPD automatikus populációja támogatott és engedélyezett, akkor az IPD-t az illesztőprogram tölti fel. Amikor az SQLCopyDesc-et az IPD-vel hívják meg SourceDescHandle-ként, a feltöltött mezők másolódnak. Ha az IPD-t nem tölti fel az illesztőprogram, az eredetileg az IPD-ben lévő mezők tartalmát másolják.

A leíró összes mezője, kivéve SQL_DESC_ALLOC_TYPE (amely meghatározza az automatikus vagy kifejezetten a leíró fogantyút kijelölve), másolva van, függetlenül attól, hogy a mező a célleíró számára van definiálva. A másolt mezők felülírják a meglévő mezőket.

Az illesztőprogram minden leíró mezőt másol, ha a SourceDescHandle és a TargetDescHandle argumentusok ugyanahhoz az illesztőhöz vannak rendelve, még akkor is, ha az illesztőprogramok két különböző kapcsolaton vagy környezetben vannak. Ha a SourceDescHandle és a TargetDescHandle argumentumok különböző illesztőprogramokhoz vannak rendelve, a Driver Manager ODBC által definiált mezőket másol, de nem másolja az illesztőgép által definiált mezőket vagy olyan mezőket, amelyeket az ODBC nem definiált a leíró típushoz.

Az SQLCopyDesc-hez való hívás azonnal megszakításra kerül, ha hiba történik.

Amikor a SQL_DESC_DATA_PTR mezőt másolják, konzisztenciá-ellenőrzést végeznek a célleírón. Ha a konzisztencia ellenőrzése sikertelen, az SQLSTATE HY021 (Inconsistent descriptor information) jelenik meg, és az SQLCopyDesc hívása azonnal megszakításra kerül. További információért a konzisztenciáellenőrzésekről lásd: "Konzisztencia ellenőrzések" az SQLSetDescRec függvényben.

A leíró fogantyúk másolhatók különböző kapcsolatok között, még akkor is, ha a kapcsolatok különböző környezetben vannak. Ha a Driver Manager azt érzékeli, hogy a forrás- és a célleíró handle-ek nem ugyanahhoz a kapcsolathoz tartoznak, és a két kapcsolat külön illesztőprogramokhoz tartozik, akkor az SQLCopyDesc-et mezőről mezőre másolva valósítja meg SQLGetDescField és SQLSetDescField segítségével.

Amikor az SQLCopyDesc-et egy SourceDescHandle hívja egy illevezetőn, egy másik illesztőn pedig TargetDescHandle-t , a SourceDescHandle hibasora törlik. Ez azért történik, mert az SQLCopyDesc ebben az esetben SQLGetDescField és SQLSetDescField hívásokkal van megvalósítva.

A defibrátor fejlécében vagy rekordban szereplő mezők leírásáért lásd: SQLSetDescField Function. További információért a leírókról lásd: Descriptors.

Táblázatok közötti sorok másolása

Egy alkalmazás másolhat adatokat egyik tábláról a másikra anélkül, hogy az alkalmazás szintjén másolná az adatokat. Ehhez az alkalmazás ugyanazokat az adatpuffereket és leíró információkat köti egy olyan utasításhoz, amely az adatokat begyűjti, valamint arra az utasításra, amely az adatokat egy másolatba helyezi. Ez megvalósítható egy alkalmazás-leíró megosztásával (egy explicit descriptor kötésével ARD-ként egy utasításra, illetve APD-ként a másikba), vagy SQLCopyDesc használatával a két állítás ARD és APD közötti kötések másolására. Ha az utasítások különböző kapcsolatokon vannak, akkor SQLCopyDesc-et kell használni. Ezen felül az SQLCopyDesc-et kell hívni, hogy lemásolják a két állítás IRD és IPD közötti kötéseit. Amikor ugyanazon a kapcsolaton lévő utasítások másolja, az illesztőprogram által visszaadott SQL_ACTIVE_STATEMENTS információtípusnak nagyobbnak kell lennie 1-nél nagyobb ahhoz, hogy ez a művelet sikeres legyen. (Ez nem igaz a másoláskor a kapcsolatok között.)

Kódpélda

A következő példában leíró műveleteket használnak a PartsSource tábla mezői másolására a PartsCopy táblába. A PartsSource tábla tartalma sorkészlet puffereibe kerül a hstmt0-ban. Ezeket az értékeket a hstmt1 egy utasítás paramétereiként INSERT használják a PartsCopy tábla oszlopainak feltöltésére. Ehhez az IRD hstmt0 mezőit az IPD hstmt1 mezőibe másoljuk, míg az ARD mezőithstmt0 APD mezőibe a hstmt1 területére. Használd az SQLSetDescField-et, hogy az IPD SQL_DESC_PARAMETER_TYPE attribútumját SQL_PARAM_INPUT-re állítsd be, amikor IRD mezőket másolsz egy kimeneti paraméterekkel rendelkező utasításból olyan IPD mezőkre, amelyeknek bemeneti paramétereknek kell lenniük.

#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  

Kapcsolódó funkciók

Lásd még

ODBC API-referencia
ODBC-fejlécfájlok