Funzione SQLProcedureColumns
Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ODBC
Riepilogo
SQLProcedureColumns restituisce l'elenco di parametri di input e output, nonché le colonne che costituiscono il set di risultati per le procedure specificate. Il driver restituisce le informazioni come set di risultati nell'istruzione specificata.
Sintassi
SQLRETURN SQLProcedureColumns(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * ProcName,
SQLSMALLINT NameLength3,
SQLCHAR * ColumnName,
SQLSMALLINT NameLength4);
Argomenti
StatementHandle
[Input] Handle di istruzione.
CatalogName
[Input] Nome catalogo procedure. Se un driver supporta cataloghi per alcune procedure ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le procedure che non dispongono di cataloghi. CatalogName non può contenere un criterio di ricerca di stringhe.
Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, CatalogName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, CatalogName è un argomento ordinario; viene trattato letteralmente e il relativo caso è significativo. Per altre informazioni, vedere Argomenti in Funzioni del catalogo.
NameLength1
[Input] Lunghezza in caratteri di *CatalogName.
SchemaName
[Input] Modello di ricerca di stringhe per i nomi degli schemi delle procedure. Se un driver supporta schemi per alcune procedure ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, una stringa vuota ("") indica le procedure che non dispongono di schemi.
Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, SchemaName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, SchemaName è un argomento del valore del modello, che viene trattato letteralmente e il relativo case è significativo.
NameLength2
[Input] Lunghezza in caratteri di *SchemaName.
ProcName
[Input] Modello di ricerca di stringhe per i nomi delle procedure.
Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, ProcName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, ProcName è un argomento del valore del criterio; viene trattato letteralmente e il relativo case è significativo.
NameLength3
[Input] Lunghezza in caratteri di *ProcName.
ColumnName
[Input] Modello di ricerca di stringhe per i nomi di colonna.
Se l'attributo dell'istruzione SQL_ATTR_METADATA_ID è impostato su SQL_TRUE, ColumnName viene considerato come identificatore e il relativo case non è significativo. Se è SQL_FALSE, ColumnName è un argomento del valore del criterio; viene trattato letteralmente e il relativo case è significativo.
NameLength4
[Input] Lunghezza in caratteri di *ColumnName.
Resi
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR o SQL_INVALID_HANDLE.
Diagnostica
Quando SQLProcedureColumns restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_STMT e handle di StatementHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLProcedureColumns e spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 08S01 | Errore del collegamento di comunicazione | Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione. |
| 24000 | Stato del cursore non valido | È stato aperto un cursore in StatementHandle e è stato chiamato SQLFetch o SQLFetchScroll. Questo errore viene restituito da Gestione driver se SQLFetch o SQLFetchScroll non ha restituito SQL_NO_DATA e viene restituito dal driver se SQLFetch o SQLFetchScroll ha restituito SQL_NO_DATA. Un cursore è stato aperto in StatementHandle, ma SQLFetch o SQLFetchScroll non è stato chiamato. |
| 40001 | Errore di serializzazione | È stato eseguito il rollback della transazione a causa di un deadlock della risorsa con un'altra transazione. |
| 40003 | Completamento istruzione sconosciuto | La connessione associata non è riuscita durante l'esecuzione di questa funzione e non è possibile determinare lo stato della transazione. |
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLError nel buffer *MessageText descrive l'errore e la relativa causa. |
| HY001 | Errore di allocazione della memoria | Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY008 | Operazione annullata | L'elaborazione asincrona è stata abilitata per StatementHandle. La funzione è stata chiamata e prima di completare l'esecuzione, SQLCancel o SQLCancelHandle è stata chiamata in StatementHandle. La funzione è stata quindi chiamata di nuovo in StatementHandle. La funzione è stata chiamata e prima del completamento dell'esecuzione, SQLCancel o SQLCancelHandle è stato chiamato su StatementHandle da un thread diverso in un'applicazione multithread. |
| HY009 | Uso non valido del puntatore Null | L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE, l'argomento CatalogName è un puntatore Null e l'SQL_CATALOG_NAME InfoType restituisce che i nomi di catalogo sono supportati. (DM) L'attributo dell'istruzione SQL_ATTR_METADATA_ID è stato impostato su SQL_TRUE e l'argomento SchemaName, ProcName o ColumnName è un puntatore Null. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata una funzione in esecuzione asincrona per l'handle di connessione associato a StatementHandle. Questa funzione aynschronous era ancora in esecuzione quando è stata chiamata la funzione SQLProcedureColumns. (DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per StatementHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi. (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per StatementHandle ed è ancora in esecuzione quando questa funzione è stata chiamata. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations o SQLSetPos è stato chiamato per StatementHandle e restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima dell'invio dei dati per tutti i parametri o le colonne data-at-execution. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) Il valore di uno degli argomenti di lunghezza del nome è minore di 0 ma non uguale a SQL_NTS. Il valore di uno degli argomenti della lunghezza del nome ha superato il valore di lunghezza massima per il nome di catalogo, schema, routine o colonna corrispondente. |
| HY117 | La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. | (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran. |
| HYC00 | Funzionalità facoltativa non implementata | È stato specificato un catalogo procedure e il driver o l'origine dati non supporta i cataloghi. È stato specificato uno schema di routine e il driver o l'origine dati non supporta gli schemi. È stato specificato un criterio di ricerca di stringhe per lo schema della routine, il nome della routine o il nome della colonna e l'origine dati non supporta i criteri di ricerca per uno o più di questi argomenti. La combinazione delle impostazioni correnti degli attributi delle istruzioni SQL_ATTR_CONCURRENCY e SQL_ATTR_CURSOR_TYPE non è supportata dal driver o dall'origine dati. L'attributo di istruzione SQL_ATTR_USE_BOOKMARKS è stato impostato su SQL_UB_VARIABLE e l'attributo dell'istruzione SQL_ATTR_CURSOR_TYPE è stato impostato su un tipo di cursore per cui il driver non supporta i segnalibri. |
| HYT00 | Timeout scaduto | Periodo di timeout scaduto prima che l'origine dati restituisca il set di risultati. Il periodo di timeout viene impostato tramite SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Il timeout della connessione è scaduto | Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Il driver non supporta questa funzione | (DM) Il driver associato a StatementHandle non supporta la funzione. |
| IM017 | Il polling è disabilitato in modalità di notifica asincrona | Ogni volta che viene usato il modello di notifica, il polling è disabilitato. |
| IM018 | SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. | Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione. |
Commenti
Questa funzione viene in genere utilizzata prima dell'esecuzione dell'istruzione per recuperare informazioni sui parametri della routine e sulle colonne che costituiscono il set di risultati o i set restituiti dalla routine, se presenti. Per altre informazioni, vedere Routine.
Nota
SQLProcedureColumns potrebbe non restituire tutte le colonne usate da una routine. Ad esempio, un driver potrebbe restituire solo informazioni sui parametri utilizzati da una routine e non sulle colonne in un set di risultati generato.
Gli argomenti SchemaName, ProcName e ColumnName accettano criteri di ricerca. Per altre informazioni sui modelli di ricerca validi, vedere Argomenti dei valori del criterio.
Nota
Per altre informazioni sull'utilizzo generale, gli argomenti e i dati restituiti delle funzioni del catalogo ODBC, vedere Funzioni del catalogo.
SQLProcedureColumns restituisce i risultati come set di risultati standard, ordinati in base a PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME e COLUMN_TYPE. I nomi delle colonne vengono restituiti per ogni routine nell'ordine seguente: il nome del valore restituito, i nomi di ogni parametro nella chiamata di routine (in ordine di chiamata) e quindi i nomi di ogni colonna nel set di risultati restituito dalla routine (in ordine di colonna).
Le applicazioni devono associare colonne specifiche del driver rispetto alla fine del set di risultati. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.
Per determinare le lunghezze effettive delle colonne PROCEDURE_CAT, PROCEDURE_SCHEM, PROCEDURE_NAME e COLUMN_NAME, un'applicazione può chiamare SQLGetInfo con le opzioni di SQL_MAX_CATALOG_NAME_LEN, SQL_MAX_SCHEMA_NAME_LEN, SQL_MAX_PROCEDURE_NAME_LEN e SQL_MAX_COLUMN_NAME_LEN.
Le colonne seguenti sono state rinominate per ODBC 3.x. Le modifiche apportate al nome della colonna non influiscono sulla compatibilità con le versioni precedenti perché le applicazioni si associano per numero di colonna.
| Colonna ODBC 2.0 | ODBC 3.x colonna |
|---|---|
| PROCEDURE_QUALIFIER | PROCEDURE_CAT |
| PROCEDURE _OWNER | PROCEDURE_SCHEM |
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
| RADIX | NUM_PREC_RADIX |
Le colonne seguenti sono state aggiunte al set di risultati restituito da SQLProcedureColumns per ODBC 3.x:
COLUMN_DEF
DATETIME_CODE
CHAR_OCTET_LENGTH
ORDINAL_POSITION
IS_NULLABLE
Nella tabella seguente sono elencate le colonne nel set di risultati. Le colonne aggiuntive successive alla colonna 19 (IS_NULLABLE) possono essere definite dal driver. Un'applicazione deve ottenere l'accesso alle colonne specifiche del driver con il conteggio dalla fine del set di risultati anziché specificare una posizione ordinale esplicita. Per altre informazioni, vedere Dati restituiti dalle funzioni del catalogo.
| Nome colonna | Column number | Tipo di dati | Commenti |
|---|---|---|---|
| PROCEDURE_CAT (ODBC 2.0) | 1 | Varchar | Nome catalogo procedure; NULL se non applicabile all'origine dati. Se un driver supporta cataloghi per alcune procedure, ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le procedure che non dispongono di cataloghi. |
| PROCEDURE_SCHEM (ODBC 2.0) | 2 | Varchar | Nome schema procedure; NULL se non applicabile all'origine dati. Se un driver supporta schemi per alcune procedure ma non per altri, ad esempio quando il driver recupera i dati da diversi DBMS, restituisce una stringa vuota ("") per le routine che non dispongono di schemi. |
| PROCEDURE_NAME (ODBC 2.0) | 3 | Varchar non NULL | Nome della procedura. Viene restituita una stringa vuota per una routine che non ha un nome. |
| COLUMN_NAME (ODBC 2.0) | 4 | Varchar non NULL | Nome colonna routine. Il driver restituisce una stringa vuota per una colonna di routine che non ha un nome. |
| COLUMN_TYPE (ODBC 2.0) | 5 | Smallint non NULL | Definisce la colonna della routine come parametro o colonna del set di risultati: SQL_PARAM_TYPE_UNKNOWN: la colonna della routine è un parametro il cui tipo è sconosciuto. (ODBC 1.0) SQL_PARAM_INPUT: la colonna della routine è un parametro di input. (ODBC 1.0) SQL_PARAM_INPUT_OUTPUT: la colonna della routine è un parametro di input/output. (ODBC 1.0) SQL_PARAM_OUTPUT: la colonna della routine è un parametro di output. (ODBC 2.0) SQL_RETURN_VALUE: la colonna della routine è il valore restituito della routine. (ODBC 2.0) SQL_RESULT_COL: la colonna della routine è una colonna del set di risultati. (ODBC 1.0) |
| DATA_TYPE (ODBC 2.0) | 6 | Smallint non NULL | Tipo di dati SQL. Può trattarsi di un tipo di dati SQL ODBC o di un tipo di dati SQL specifico del driver. Per i tipi di dati datetime e interval, questa colonna restituisce i tipi di dati concisi, ad esempio SQL_TYPE_TIME o SQL_INTERVAL_YEAR_TO_MONTH. Per un elenco dei tipi di dati SQL ODBC validi, vedere Tipi di dati SQL nell'Appendice D: Tipi di dati. Per informazioni sui tipi di dati SQL specifici del driver, vedere la documentazione del driver. |
| TYPE_NAME (ODBC 2.0) | 7 | Varchar non NULL | Nome del tipo di dati dipendente dall'origine dati; ad esempio "CHAR", "VARCHAR", "MONEY", "LONG VARBINARY" o "CHAR ( ) FOR BIT DATA". |
| COLUMN_SIZE (ODBC 2.0) | 8 | Integer | Dimensioni della colonna della routine nell'origine dati. Viene restituito NULL per i tipi di dati in cui le dimensioni della colonna non sono applicabili. Per altre informazioni sulla precisione, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione nell'Appendice D: Tipi di dati. |
| BUFFER_LENGTH (ODBC 2.0) | 9 | Integer | Lunghezza in byte di dati trasferiti in un'operazione SQLGetData o SQLFetch se viene specificato SQL_C_DEFAULT. Per i dati numerici, queste dimensioni possono essere diverse dalle dimensioni dei dati archiviati nell'origine dati. Per altre informazioni, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione, nell'Appendice D: Tipi di dati. |
| DECIMAL_DIGITS (ODBC 2.0) | 10 | Smallint | Cifre decimali della colonna della routine nell'origine dati. Viene restituito NULL per i tipi di dati in cui le cifre decimali non sono applicabili. Per altre informazioni sulle cifre decimali, vedere Dimensioni delle colonne, Cifre decimali, Lunghezza ottetto di trasferimento e Dimensioni di visualizzazione, nell'Appendice D: Tipi di dati. |
| NUM_PREC_RADIX (ODBC 2.0) | 11 | Smallint | Per i tipi di dati numerici, 10 o 2. Se 10, i valori in COLUMN_SIZE e DECIMAL_DIGITS assegnare il numero di cifre decimali consentite per la colonna. Ad esempio, una colonna DECIMAL(12,5) restituisce un NUM_PREC_RADIX di 10, un COLUMN_SIZE di 12 e un DECIMAL_DIGITS di 5; Una colonna FLOAT può restituire un NUM_PREC_RADIX di 10, un COLUMN_SIZE di 15 e un DECIMAL_DIGITS di NULL. Se 2, i valori in COLUMN_SIZE e DECIMAL_DIGITS assegnare il numero di bit consentiti nella colonna. Ad esempio, una colonna FLOAT potrebbe restituire un NUM_PREC_RADIX pari a 2, un COLUMN_SIZE di 53 e un DECIMAL_DIGITS null. Viene restituito NULL per i tipi di dati in cui NUM_PREC_RADIX non è applicabile. |
| NULLABLE (ODBC 2.0) | 12 | Smallint non NULL | Indica se la colonna della routine accetta un valore NULL: SQL_NO_NULLS: la colonna della routine non accetta valori NULL. SQL_NULLABLE: la colonna della routine accetta valori NULL. SQL_NULLABLE_UNKNOWN: non è noto se la colonna della routine accetta valori NULL. |
| OSSERVAZIONI (ODBC 2.0) | 13 | Varchar | Descrizione della colonna della routine. |
| COLUMN_DEF (ODBC 3.0) | 14 | Varchar | Valore predefinito della colonna. Se è stato specificato NULL come valore predefinito, questa colonna è la parola NULL, non racchiusa tra virgolette. Se il valore predefinito non può essere rappresentato senza troncamento, questa colonna contiene TRUNCATED, senza virgolette singole racchiuse tra virgolette singole. Se non è stato specificato alcun valore predefinito, questa colonna è NULL. Il valore di COLUMN_DEF può essere usato per generare una nuova definizione di colonna, tranne quando contiene il valore TRUNCATED. |
| SQL_DATA_TYPE (ODBC 3.0) | 15 | Smallint non NULL | Valore del tipo di dati SQL visualizzato nel campo SQL_DESC_TYPE del descrittore. Questa colonna corrisponde alla colonna DATA_TYPE, ad eccezione dei tipi di dati datetime e interval. Per i tipi di dati datetime e interval, il campo SQL_DATA_TYPE nel set di risultati restituirà SQL_INTERVAL o SQL_DATETIME e il campo SQL_DATETIME_SUB restituirà il codice secondario per l'intervallo o il tipo di dati datetime specifico. (Vedere Appendice D: Tipi di dati. |
| SQL_DATETIME_SUB (ODBC 3.0) | 16 | Smallint | Codice del sottotipo per i tipi di dati datetime e interval. Per gli altri tipi di dati in questa colonna viene restituito NULL. |
| CHAR_OCTET_LENGTH (ODBC 3.0) | 17 | Integer | Lunghezza massima in byte di una colonna di tipo carattere o binario. Per gli tutti gli altri tipi di dati, il valore di questa colonna è NULL. |
| ORDINAL_POSITION (ODBC 3.0) | 18 | Integer non NULL | Per i parametri di input e output, la posizione ordinale del parametro nella definizione della routine (in ordine dei parametri crescente, a partire da 1). Per un valore restituito (se disponibile), viene restituito 0. Per le colonne del set di risultati, la posizione ordinale della colonna nel set di risultati, con la prima colonna nel set di risultati numero 1. Se sono presenti più set di risultati, le posizioni ordinali della colonna vengono restituite in modo specifico del driver. |
| IS_NULLABLE (ODBC 3.0) | 19 | Varchar | "NO" se la colonna non include valori NULL. "SÌ" se la colonna può includere valori NULL. Quando non è noto se i valori Null sono supportati, in questa colonna viene restituita una stringa di lunghezza zero. Per determinare il supporto di valori Null vengono seguite le regole ISO. In un sistema DBMS conforme a ISO SQL non vengono restituite stringhe vuote. Il valore restituito per questa colonna è diverso dal valore restituito per la colonna NULLABLE. Vedere la descrizione della colonna NULLABLE. |
Esempio di codice
Vedere Chiamate di procedura.
Funzioni correlate
| Per informazioni su | Vedere |
|---|---|
| Associazione di un buffer a una colonna in un set di risultati | Funzione SQLBindCol |
| Annullamento dell'elaborazione delle istruzioni | Funzione SQLCancel |
| Recupero di una singola riga o di un blocco di dati in una direzione forward-only | Funzione SQLFetch |
| Recupero di un blocco di dati o scorrimento di un set di risultati | Funzione SQLFetchScroll |
| Restituzione di un elenco di procedure in un'origine dati | Funzione SQLProcedures |