Utilizzi dei parametri con valori di tabella in ODBC
In questo argomento vengono illustrati gli scenari utente principali relativi all'utilizzo dei parametri con valori di tabella in ODBC:
Parametro con valori di tabella con buffer a più righe completamente associati (invio di dati come TVP con tutti i valori in memoria)
Parametro con valori di tabella con flusso di righe (invio di dati come TVP mediante data-at-execution)
Recupero di metadati del parametro con valori di tabella dal catalogo di sistema
Recupero di metadati del parametro con valori di tabella per un'istruzione preparata
Parametro con valori di tabella con buffer a più righe completamente associati (invio di dati come TVP con tutti i valori in memoria)
Se utilizzato con buffer a più righe completamente associati, tutti i valori del parametro sono disponibili in memoria. È tipico, ad esempio, di una transazione OLTP nella quale i parametri con valori di tabella possono essere assemblati in una singola stored procedure. Senza parametri con valori di tabella, risulta necessario generare dinamicamente un batch complesso con più istruzioni o effettuare più chiamate al server.
Il parametro con valori di tabella viene associato tramite SQLBindParameter insieme agli altri parametri. Dopo avere associato tutti i parametri, l'applicazione imposta l'attributo dello stato attivo del parametro, SQL_SOPT_SS_PARAM_FOCUS, in ogni parametro con valori di tabella e chiama SQLBindParameter per le colonne del parametro con valori di tabella.
Il tipo di server per un parametro con valori di tabella è un nuovo tipo specifico per SQL Server, SQL_SS_TABLE. Il tipo C dell'associazione per SQL_SS_TABLE deve essere sempre SQL_C_DEFAULT. Non vengono trasferiti dati per il parametro associato al parametro con valori di tabella; viene utilizzato per passare i metadati delle tabelle e per controllare il modo in cui passare i dati nelle colonne che costituiscono il parametro con valori di tabella.
La lunghezza del parametro con valori di tabella è impostata sul numero di righe inviate al server. Il parametro ColumnSize di SQLBindParameter per un parametro con valori di tabella specifica il numero massimo di righe che è possibile inviare. Rappresenta la dimensione della matrice dei buffer delle colonne. ParameterValuePtr è il buffer del parametro, per un parametro con valori di tabella in SQLBindParameter. ParameterValuePtr e il relativo parametro associato BufferLength vengono utilizzati per passare il nome del tipo del parametro con valori di tabella quando necessario. Il nome del tipo non è necessario per le chiamate alle stored procedure, mentre è necessario per le istruzioni SQL.
Quando viene specificato in una chiamata a SQLBindParameter, il nome del tipo del parametro con valori di tabella deve essere sempre specificato come valore Unicode, anche nelle applicazioni generate come applicazioni ANSI. Quando un nome del tipo del parametro con valori di tabella viene specificato tramite SQLSetDescField, è possibile utilizzare un valore letterale conforme al modo in cui è stata generata l'applicazione. In Gestione driver ODBC verrà eseguita la conversione Unicode necessaria.
I metadati per i parametri con valori di tabella e le colonne dei parametri con valori di tabella possono essere modificati singolarmente e in modo esplicito tramite SQLGetDescRec, SQLSetDescRec, SQLGetDescField e SQLSetDescField. Tuttavia, l'overload di SQLBindParameter è generalmente più comodo e nella maggior parte dei casi non richiede l'accesso esplicito al descrittore. Questo approccio è coerente con la definizione di SQLBindParameter per altri tipi di dati, ad eccezione del fatto che i campi di descrizione interessati per un parametro con valori di tabella sono leggermente diversi.
Un'applicazione utilizza talvolta un parametro con valori di tabella con le istruzioni SQL dinamiche ed è necessario fornire il nome del tipo del parametro con valori di tabella. Se in tal caso il parametro con valori di tabella non viene definito nello schema predefinito corrente per la connessione, SQL_CA_SS_TYPE_CATALOG_NAME e SQL_CA_SS_TYPE_SCHEMA_NAME devono essere impostati tramite SQLSetDescField. Poiché le definizioni del tipo di tabella e i parametri con valori di tabella devono risiedere nello stesso database, SQL_CA_SS_TYPE_CATALOG_NAME non deve essere impostato se l'applicazione utilizza parametri con valori di tabella. In caso contrario, SQLSetDescField genererà un errore.
Il codice di esempio per questo scenario è nella procedura demo_fixed_table-valued parameter_binding nell'applicazione di esempio disponibile in CodePlex; per ulteriori informazioni, vedere Esempi del Motore di database di SQL Server.
Parametro con valori di tabella con flusso di righe (invio di dati come TVP mediante data-at-execution)
In questo scenario l'applicazione fornisce le righe al driver nel modo in cui vengono richieste, le quali vengono poi trasferite al server. In questo modo si evita di dovere memorizzare tutte le righe nel buffer di memoria. Tale condizione è rappresentativa negli scenari di inserimento/aggiornamento bulk. Le prestazioni dei parametri con valori di tabella sono a metà tra le matrici di parametri e la copia bulk. La programmazione dei parametri con valori di tabella è semplice quanto quella delle matrici di parametri, ma offre una maggiore flessibilità sul lato server.
Il parametro con valori di tabella e le relative colonne vengono associate come descritto nella sezione precedente, Parametro con valori di tabella con buffer a più righe completamente associati, impostando però l'indicatore della lunghezza del parametro con valori di tabella su SQL_DATA_AT_EXEC. Il driver risponde a SQLExecute o SQLExecuteDirect nel modo consueto per i parametri data-at-execution, ovvero restituendo SQL_NEED_DATA. Quando il driver è pronto per accettare i dati per un parametro con valori di tabella, SQLParamData restituisce il valore di ParameterValuePtr in SQLBindParameter.
Un'applicazione utilizza SQLPutData per un parametro con valori di tabella per indicare la disponibilità dei dati per le colonne che costituiscono il parametro con valori di tabella. Quando SQLPutData viene chiamato per un parametro con valori di tabella, DataPtr deve essere sempre null e StrLen_or_Ind deve essere 0 o un numero minore o uguale alla dimensione della matrice specificata per i buffer del parametro con valori di tabella (il parametro ColumnSize di SQLBindParameter). 0 significa che non ci sono più righe per il parametro con valori di tabella e il driver procederà con l'elaborazione fino al successivo parametro effettivo della procedura. Quando StrLen_or_Ind non è 0, il driver elaborerà le colonne che costituiscono il parametro con valori di tabella nello stesso modo dei parametri associati al parametro non con valori di tabella. Ogni colonna del parametro con valori di tabella può specificare la lunghezza effettiva dei dati, SQL_NULL_DATA, o può specificare un parametro data-at-execution tramite il buffer di lunghezza/indicatore. I valori delle colonne del parametro con valori di tabella possono essere passati da chiamate ripetute a SQLPutData nello stesso modo in cui vengono passati in parti un valore binario o carattere.
Una volta elaborate tutte le colonne del parametro con valori di tabella, il driver torna al parametro con valori di tabella per elaborare ulteriori righe di dati del parametro con valori di tabella. Pertanto, per i parametri con valori di tabella data-at-execution il driver non segue la solita scansione sequenziale dei parametri associati. Un parametro con valori di tabella associato viene sottoposto a polling finché non viene chiamato SQLPutData con StrLen_Or_IndPtr uguale a 0, dopodiché il driver salta le colonne del parametro con valori di tabella e si sposta al parametro effettivo successivo della stored procedure. Quando SQLPutData passa un valore dell'indicatore maggiore o uguale 1, il driver elabora le righe e le colonne del parametro con valori di tabella in sequenza finché non ottiene i valori per tutte le righe e le colonne associate. Dopodiché il driver torna al parametro con valori di tabella. Tra la ricezione del token per il parametro con valori di tabella da SQLParamData e la chiamata a SQLPutData(hstmt, NULL, n) per un parametro con valori di tabella, l'applicazione deve impostare i dati delle colonne che costituiscono il parametro con valori di tabella e il contenuto del buffer di indicatore per la riga o le righe successive da passare al server.
Il codice di esempio per questo scenario è nella routine demo_variable_table-valued parameter_binding nell'applicazione di esempio disponibile in CodePlex; per ulteriori informazioni, vedere Esempi del Motore di database di SQL Server.
Recupero di metadati del parametro con valori di tabella dal catalogo di sistema
Quando un'applicazione chiama SQLProcedureColumns per una procedura contenente parametri con valori di tabella, DATA_TYPE viene restituito come SQL_SS_TABLE e TYPE_NAME è il nome del tipo di tabella per il parametro con valori di tabella. Vengono aggiunte altre due colonne al set di risultati restituito da SQLProcedureColumns: SS_TYPE_CATALOG_NAME restituisce il nome del catalogo in cui è definito il tipo di tabella del parametro con valori di tabella e SS_TYPE_SCHEMA_NAME restituisce il nome dello schema in cui è definito il tipo di tabella del parametro con valori di tabella. In conformità con la specifica ODBC, SS_TYPE_CATALOG_NAME e SS_TYPE_SCHEMA_NAME vengono visualizzati prima di tutte le colonne specifiche del driver che sono state aggiunte nelle versioni precedenti di SQL Server e dopo tutte le colonne richieste da ODBC stesso.
Le nuove colonne verranno popolate non solo per i parametri con valori di tabella, ma anche per i parametri del tipo CLR definito dall'utente. Le colonne esistenti dello schema e del catalogo dei parametri UDT verranno ancora popolate, ma la disponibilità di colonne comuni per lo schema e il catalogo da utilizzare per i tipi di dati semplificherà in futuro lo sviluppo di applicazioni. Notare che le raccolte di schemi XML sono piuttosto diverse e non sono incluse in questa modifica.
Un'applicazione utilizza SQLTables per determinare i nomi dei tipi di tabella nello stesso modo utilizzato per le tabelle persistenti, le tabelle di sistema e le viste. Viene introdotto un nuovo tipo di tabella, TABLE TYPE, per consentire a un'applicazione di identificare i tipi di tabella associati ai parametri con valori di tabella. I tipi di tabella e le tabelle normali utilizzano spazi dei nomi diversi. È pertanto possibile utilizzare lo stesso nome per un tipo di tabella e una tabella effettiva. A tale scopo è stato introdotto un nuovo attributo dell'istruzione, SQL_SOPT_SS_NAME_SCOPE. Questo attributo specifica se SQLTables e le altre funzioni di catalogo che accettano un nome di tabella come parametro devono interpretare il nome di tabella come nome di una tabella effettiva o come nome di un tipo di tabella.
Un'applicazione utilizza SQLColumns per determinare le colonne per un tipo di tabella nello stesso modo utilizzato per le tabelle persistenti, ma è necessario prima impostare SQL_SOPT_SS_NAME_SCOPE per indicare che l'ambito è relativo ai tipi di tabella anziché alle tabelle effettive. Anche SQLPrimaryKeys può essere utilizzato con i tipi di tabella, impostando sempre SQL_SOPT_SS_NAME_SCOPE.
Il codice di esempio per questo scenario è nella routine demo_metadata_from_catalog_APIs nell'applicazione di esempio disponibile in CodePlex; per ulteriori informazioni, vedere Esempi del Motore di database di SQL Server.
Recupero di metadati del parametro con valori di tabella per un'istruzione preparata
In questo scenario un'applicazione utilizza SQLNumParameters e SQLDescribeParam per recuperare i metadati per i parametri con valori di tabella.
Il campo IPD SQL_CA_SS_TYPE_NAME viene utilizzato per recuperare il nome del tipo per il parametro con valori di tabella. I campi IPD SQL_CA_SS_TYPE_SCHEMA_NAME e SQL_CA_SS_TYPE_CATALOG_NAME vengono utilizzati per recuperare rispettivamente il catalogo e lo schema.
Le definizioni del tipo di tabella e i parametri con valori di tabella devono risiedere nello stesso database. SQLSetDescField genererà un errore se un'applicazione imposta SQL_CA_SS_TYPE_CATALOG_NAME quando si utilizzano i parametri con valori di tabella.
SQL_CA_SS_TYPE_CATALOG_NAME e SQL_CA_SS_TYPE_SCHEMA_NAME possono inoltre essere utilizzati per recuperare il catalogo e lo schema associati ai parametri del tipo CLR definito dall'utente. SQL_CA_SS_TYPE_CATALOG_NAME and SQL_CA_SS_TYPE_SCHEMA_NAME sono le alternative agli attributi esistenti specifici del tipo per il catalogo e lo schema per i tipi CLR UDT.
In questo scenario un'applicazione utilizza inoltre SQLColumns per recuperare i metadati della colonna per un parametro con valori di tabella, perché SQLDescribeParam non restituisce i metadati della colonna per un parametro con valori di tabella.
Il codice di esempio per questo caso di utilizzo è nella routine demo_metadata_from_prepared_statement nell'applicazione di esempio disponibile in CodePlex; per ulteriori informazioni, vedere Esempi del Motore di database di SQL Server.
Cronologia modifiche
Aggiornamento del contenuto |
|---|
Aggiornamento dei collegamenti agli esempi. |