Extensibility Framework API untuk SQL Server

Berlaku untuk: SQL Server 2019 (15.x) dan versi yang lebih baru

Anda dapat menggunakan kerangka kerja ekstensibilitas untuk menulis ekstensi bahasa pemrograman untuk SQL Server. Extensibility Framework API untuk SQL Server adalah API yang dapat digunakan oleh ekstensi bahasa untuk berinteraksi dan bertukar data dengan SQL Server.

Sebagai penulis ekstensi bahasa, Anda dapat menggunakan referensi ini bersama dengan ekstensi bahasa sumber terbuka untuk memahami cara menggunakan API untuk menulis sendiri. Anda dapat menemukan kode sumber untuk ekstensi bahasa di aka.ms/mssql-lang-extensions.

Anda dapat menemukan sintaksis dan informasi argumen tentang semua fungsi API dalam artikel ini.

Nilai hasil

Semua fungsi mengembalikan SQLRETURN parameter. Jika nilainya selain SQL_SUCCESS, nilai diperlakukan sebagai kesalahan dan eksekusi skrip berhenti.

Output standar

Setiap output oleh ekstensi ke output standar atau aliran kesalahan dilacak ke file log sesi, dan akhirnya ditelusuri kembali ke SQL Server. Ini mirip dengan apa pun yang ditampilkan di tab pesan SQL Server Management Studio (SSMS).

Init

Fungsi ini hanya disebut sekali dan digunakan untuk menginisialisasi runtime untuk eksekusi.

Sintaks

SQLRETURN Init(
    SQLCHAR *ExtensionParams,
    SQLULEN ExtensionParamsLength,
    SQLCHAR *ExtensionPath,
    SQLULEN ExtensionPathLength,
    SQLCHAR *PublicLibraryPath,
    SQLULEN PublicLibraryPathLength,
    SQLCHAR *PrivateLibraryPath,
    SQLULEN PrivateLibraryPathLength
);

Argumen

Argumen Input/output Deskripsi
ExtensionParams Input String yang dihentikan null berisi PARAMETERS nilai yang disediakan selama CREATE EXTERNAL LANGUAGE atau ALTER EXTERNAL LANGUAGE
ExtensionParamsLength Input Panjang dalam byte ExtensionParams (tidak termasuk karakter penghentian null)
ExtensionPath Input String UTF-8 yang dihentikan null yang berisi jalur absolut ke direktori penginstalan ekstensi
ExtensionPathLength Input Panjang dalam byte ExtensionPath (tidak termasuk karakter penghentian null)
PublicLibraryPath Input String UTF-8 yang dihentikan null yang berisi jalur absolut ke direktori pustaka eksternal publik untuk bahasa eksternal ini
PublicLibraryPathLength Input Panjang dalam byte PublicLibraryPath (tidak termasuk karakter penghentian null)
PrivateLibraryPath Input String UTF-8 yang dihentikan null yang berisi jalur absolut ke direktori pustaka eksternal privat untuk pengguna ini dan bahasa eksternal ini
PrivateLibraryPathLength Input Panjang dalam byte PrivateLibraryPath (tidak termasuk karakter penghentian null)

InitSession

Fungsi ini dipanggil sekali per sesi dan menginisialisasi pengaturan khusus sesi.

Sintaks

SQLRETURN InitSession(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLCHAR*        Script,
    SQLULEN         ScriptLength,
    SQLUSMALLINT    InputSchemaColumnsNumber,
    SQLUSMALLINT    ParametersNumber
    SQLCHAR*        InputDataName,
    SQLUSMALLINT    InputDataNameLength,
    SQLCHAR*        OutputDataName,
    SQLUSMALLINT    OutputDataNameLength
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
Script Input String UTF-8 yang dihentikan null yang berisi @script dalam sp_execute_external_script
ScriptLength Input Panjang dalam byte ScriptScript (tidak termasuk karakter penghentian null)
InputSchemaColumnsNumber Input Jumlah kolom dalam tataan hasil dari @input_data_1 dalam sp_execute_external_script
ParametersNumber Input Jumlah parameter input dari @params dalam sp_execute_external_script
InputDataName Input String UTF-8 yang dihentikan null yang berisi @input_data_1_name dalam sp_execute_external_script
InputDataNameLength Input Panjang dalam byte InputDataName (tidak termasuk karakter penghentian null)
OutputDataName Input String UTF-8 yang dihentikan null yang berisi @output_data_1_name dalam sp_execute_external_script
OutputDataNameLength Input Panjang dalam byte OutputDataName (tidak termasuk karakter penghentian null)

InitColumn

Menginisialisasi informasi untuk kolom tertentu untuk sesi tertentu.

Fungsi ini dipanggil untuk setiap kolom dalam hasil yang diatur dari @input_data_1 dalam sp_execute_external_script.

Struktur kolom dari kumpulan hasil ini disebut sebagai skema input.

Sintaks

SQLRETURN InitColumn(
    SQLGUID       SessionId,
    SQLUSMALLINT  TaskId,
    SQLUSMALLINT  ColumnNumber,
    SQLCHAR*      ColumnName,
    SQLSMALLINT   ColumnNameLength,
    SQLSMALLINT   DataType,
    SQLULEN       ColumnSize,
    SQLSMALLINT   DecimalDigits,
    SQLSMALLINT   Nullable,
    SQLSMALLINT   PartitionByNumber,
    SQLSMALLINT   OrderByNumber
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
ColumnNumber Input Bilangan bulat yang mengidentifikasi indeks kolom ini dalam skema input. Kolom diberi nomor secara berurutan dalam urutan peningkatan mulai dari 0
ColumnName Input String UTF-8 yang dihentikan null yang berisi nama kolom
ColumnNameLength Input Panjang dalam byte ColumnName (tidak termasuk karakter penghentian null)
Data type Input Tipe ODBC C yang mengidentifikasi tipe data kolom ini
ColumnSize Input Ukuran maksimum dalam byte data yang mendasar di kolom ini.

Untuk SQL_C_CHARjenis data , SQL_C_WCHAR dan SQL_C_BINARY , nilai yang lebih besar dari 8.000 menunjukkan kolom ini mewakili objek LOB, dengan ukuran hingga 2 GB
DecimalDigits Input Digit desimal data yang mendasar dalam kolom ini, seperti yang ditentukan oleh Digit Desimal
Nullable Input Nilai yang menunjukkan apakah kolom ini mungkin berisi NULL nilai. Nilai yang mungkin:

- SQL_NO_NULLS: Kolom tidak boleh berisi NULL nilai.
- SQL_NULLABLE: Kolom dapat berisi NULL nilai
PartitionByNumber Input Nilai yang menunjukkan indeks kolom ini dalam @input_data_1_partition_by_columns urutan dalam sp_execute_external_script. Kolom diberi nomor secara berurutan dalam meningkatkan urutan mulai dari 0. Jika kolom ini tidak disertakan dalam urutan, nilainya adalah -1
OrderByNumber Input Nilai yang menunjukkan indeks kolom ini dalam @input_data_1_order_by_columns urutan dalam sp_execute_external_script. Kolom diberi nomor secara berurutan dalam meningkatkan urutan mulai dari 0. Jika kolom ini tidak disertakan dalam urutan, nilainya adalah -1

InitParam

Inisialisasi informasi mengenai parameter input tertentu untuk sesi tertentu.

Fungsi ini dipanggil untuk setiap parameter dari @params dalam sp_execute_external_script.

Sintaks

SQLRETURN InitParam(
    SQLGUID      SessionId,
    SQLUSMALLINT TaskId,
    SQLUSMALLINT ParamNumber,
    SQLCHAR*     ParamName,
    SQLSMALLINT  ParamNameLength,
    SQLSMALLINT  DataType,
    SQLULEN      ParamSize,
    SQLSMALLINT  DecimalDigits,
    SQLPOINTER   ParamValue,
    SQLINTEGER   StrLen_or_Ind,
    SQLSMALLINT  InputOutputType
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
ParamNumber Input Bilangan bulat yang mengidentifikasi indeks parameter ini. Parameter dinomorkan secara berurutan dalam meningkatkan urutan mulai dari 0
ParamName Input String UTF-8 yang dihentikan null yang berisi nama parameter
ParamNameLength Input Panjang dalam byte ParamName (tidak termasuk karakter penghentian null)
Data type Input Jenis ODBC C yang mengidentifikasi jenis data parameter ini
ParamSize Input Ukuran maksimum dalam byte data yang mendasar dalam parameter ini.

Untuk SQL_C_CHAR, SQL_C_WCHAR dan SQL_C_BINARY jenis data, nilai yang lebih besar dari 8000 menunjukkan parameter ini mewakili objek LOB dan dengan ukuran hingga 2 GB
DecimalDigits Input Digit desimal data yang mendasar dalam parameter ini, seperti yang didefinisikan oleh Digit Desimal
ParamValue Input Penunjuk ke buffer yang berisi nilai parameter
StrLen_or_Ind Input Nilai bilangan bulat yang menunjukkan panjang dalam byte ParamValue, atau SQL_NULL_DATA untuk menunjukkan bahwa data adalah NULL.

StrLen_or_Ind[col] dapat diabaikan jika kolom tidak dapat diubah ke null dan tidak mewakili salah satu jenis data berikut: SQL_C_CHAR, , SQL_C_WCHAR dan SQL_C_BINARY, SQL_C_NUMERIC atau SQL_C_TYPE_TIMESTAMP. Jika tidak, ia menunjuk ke array yang valid dengan RowsNumber elemen, di mana setiap elemen berisi panjang atau data indikator null
InputOutputType Input Jenis parameter. Argumen InputOutputType adalah salah satu nilai berikut:

- SQL_PARAM_INPUT
- SQL_PARAM_INPUT_OUTPUT

Jalankan

Jalankan @script dalam sp_execute_external_script.

Fungsi ini mungkin dipanggil beberapa kali. Sekali untuk setiap gugus uap dan untuk setiap partisi dalam @input_data_1_partition_by_columns sp_execute_external_script.

Sintaks

SQLRETURN Execute(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN         RowsNumber,
    SQLPOINTER*     Data,
    SQLINTEGER**    StrLen_or_Ind,
    SQLUSMALLINT*   OutputSchemaColumnsNumber
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
RowsNumber Input Jumlah baris dalam Data
Data Input Array dua dimensi yang berisi kumpulan @input_data_1 hasil dalam sp_execute_external_script.

Jumlah total kolom adalah InputSchemaColumnsNumber yang diterima dalam panggilan InitSession . Setiap kolom berisi RowsNumber elemen yang harus ditafsirkan sesuai dengan jenis kolom dari InitColumn.
Elemen yang ditunjukkan berada NULL di tidak dijamin StrLen_or_Ind valid dan harus diabaikan
StrLen_or_Ind Input Array dua dimensi yang berisi indikator panjang/NULL untuk setiap nilai dalam Data. Nilai yang mungkin dari setiap sel:

- n, di mana n > 0. Menunjukkan panjang data dalam byte
- SQL_NULL_DATA, menunjukkan NULL nilai.
Jumlah total kolom adalah InputSchemaColumnsNumber yang diterima dalam panggilan InitSession . Setiap kolom berisi RowsNumber elemen yang harus ditafsirkan sesuai dengan jenis kolom dari InitColumn.
StrLen_or_Ind[col] dapat diabaikan, jika satu kolom tidak dapat diubah ke null dan tidak mewakili salah satu jenis data berikut: SQL_C_CHAR, , SQL_C_WCHAR dan SQL_C_BINARY, SQL_C_NUMERIC atau SQL_C_TYPE_TIMESTAMP. Jika tidak, ia menunjuk ke array yang valid dengan RowsNumber elemen, setiap elemen berisi panjang atau data indikator null
OutputSchemaColumnsNumber Output Penunjuk ke buffer untuk mengembalikan jumlah kolom dalam kumpulan hasil yang @script diharapkan dalam sp_execute_external_script

GetResultColumn

Ambil informasi mengenai kolom output tertentu untuk sesi tertentu.

Fungsi ini dipanggil untuk setiap kolom dalam hasil yang diatur dari @script dalam sp_execute_external_script.

Struktur kolom dari kumpulan hasil ini disebut sebagai skema output.

Sintaks

SQLRETURN GetResultColumn(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLUSMALLINT    ColumnNumber,
    SQLSMALLINT*    DataType,
    SQLINTEGER*     ColumnSize,
    SQLSMALLINT*    DecimalDigits,
    SQLSMALLINT*    Nullable
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
ColumnNumber Input Bilangan bulat yang mengidentifikasi indeks kolom ini dalam skema output. Kolom diberi nomor secara berurutan dalam urutan peningkatan mulai dari 0
Data type Output Penunjuk ke buffer yang berisi tipe ODBC C yang mengidentifikasi jenis data kolom ini
ColumnSize Output Penunjuk ke buffer yang berisi ukuran maksimum dalam byte data yang mendasar dalam kolom ini
DecimalDigits Output Penunjuk ke buffer yang berisi digit desimal data yang mendasar dalam kolom ini, seperti yang didefinisikan oleh Digit Desimal. Jika jumlah digit desimal tidak dapat ditentukan atau tidak berlaku, nilai akan dibuang
Nullable Output Penunjuk ke buffer yang berisi nilai, yang menunjukkan apakah kolom ini mungkin berisi NULL nilai. Nilai yang mungkin:

- SQL_NO_NULLS: Kolom tidak boleh berisi NULL nilai.
- SQL_NULLABLE: Kolom dapat berisi NULL nilai.
Jika nilai lain diteruskan, maka eksekusi akan berhenti

GetResults

Ambil tataan hasil dari menjalankan @script sp_execute_external_script.

Fungsi ini mungkin dipanggil beberapa kali. Sekali untuk setiap gugus uap dan untuk setiap partisi dalam @input_data_1_partition_by_columns sp_execute_external_script.

Sintaks

SQLRETURN GetResults(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN*        RowsNumber,
    SQLPOINTER**    Data,
    SQLINTEGER***   StrLen_or_Ind
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
RowsNumber Output Penunjuk ke buffer yang berisi jumlah baris dalam Data
Data Output Penunjuk ke array dua dimensi yang dialokasikan oleh ekstensi yang berisi kumpulan @script hasil dalam sp_execute_external_script.

Jumlah total kolom harus OutputSchemaColumnsNumber yang diambil dalam panggilan Jalankan. Setiap kolom harus berisi RowsNumber elemen yang harus ditafsirkan sesuai dengan jenis kolom dari GetResultColumn
StrLen_or_Ind Output Penunjuk ke array dua dimensi yang dialokasikan oleh ekstensi yang berisi indikator panjang/NULL untuk setiap nilai dalam Data. Nilai yang mungkin dari setiap sel:

- n, di mana n > 0. Menunjukkan panjang data dalam byte
- SQL_NULL_DATA, menunjukkan NULL nilai.
Jumlah total kolom harus OutputSchemaColumnsNumber yang diterima dalam panggilan Jalankan. Setiap kolom berisi RowsNumber elemen yang harus ditafsirkan sesuai dengan jenis kolom dari GetResultColumn.
StrLen_or_Ind[col] diabaikan, jika satu kolom tidak dapat diubah ke null dan tidak mewakili salah satu jenis data berikut: SQL_C_CHAR, SQL_C_WCHAR dan SQL_C_BINARY [add dates]. Jika tidak, ia menunjuk ke array yang valid dengan RowsNumber elemen, setiap elemen berisi panjang atau data indikator null

GetOutputParam

Ambil informasi mengenai parameter output tertentu untuk sesi tertentu.

Fungsi ini dipanggil untuk setiap parameter dari @params dalam sp_execute_external_script ditandai dengan OUTPUT.

Sintaks

SQLRETURN GetOutputParam(
    SQLGUID        SessionId,
    SQLUSMALLINT   ParamNumber,
    SQLPOINTER*    ParamValue,
    SQLINTEGER*    StrLen_or_Ind
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
ParamValue Output Penunjuk ke buffer yang berisi nilai parameter
StrLen_or_Ind Output Penunjuk ke buffer yang berisi nilai bilangan bulat yang menunjukkan panjang dalam byte ParamValue, atau SQL_NULL_DATA untuk menunjukkan bahwa data tersebut NULL

GetInterfaceVersion

Ambil versi antarmuka.

Fungsi ini mengembalikan bilangan bulat yang mewakili versi antarmuka ekstensi.

Nilai yang didukung:

  1. Versi 1 adalah versi API awal. Didukung di RTM SQL Server 2019 (15.x).
  2. Versi 2 telah menambahkan dukungan untuk InstallExternalLibrary DAN UninstallExternalLibrary API dan didukung dari SQL Server 2019 (15.x) CU 3.

Sintaks

SQLUSMALLINT GetInterfaceVersion();

CleanupSession

Bersihkan informasi per sesi.

Sintaks

SQLRETURN CleanupSession(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri

Pembersihan

Bersihkan informasi bersama global (misalnya, JVM).

Sintaks

SQLRETURN Cleanup();

GetTelemetryResults

Mengambil data telemetri (pasangan kunci-nilai) dari ekstensi. Fungsi ini bersifat opsional dan tidak memerlukan implementasi. Telemetri diekspos oleh dm_db_external_script_execution_stats tampilan manajemen dinamis (DMV).

Ada penghitung bernama script_executions, yang dikirim oleh kerangka kerja. Ekstensi tidak boleh menggunakan nama ini.

Setiap entri telemetri adalah pasangan kunci-nilai. Kuncinya adalah string. Nilainya adalah bilangan bulat 64-bit, atau penghitung. Dengan demikian, output terdiri dari dua array logis: nama dan penghitung yang sesuai. Setiap array adalah output.

Panjang setiap array adalah RowsNumber, yang merupakan output. Output logis pertama berisi penunjuk ke string. Ini diwakili oleh dua array: CounterNames (data string aktual) dan CounterNamesLength (panjang setiap string). Output logis kedua disimpan di penunjuk CounterValues .

Sintaks

SQLRETURN GetTelemetryResults(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId,
    SQLUINTEGER    *RowsNumber,
    SQLCHAR        ***CounterNames,
    SQLINTEGER     **CounterNamesLength,
    SQLBIGINT      **CounterValues
);

Argumen

Argumen Input/output Deskripsi
SessionId Input GUID secara unik mengidentifikasi sesi skrip ini
TaskId Input Bilangan bulat secara unik mengidentifikasi proses eksekusi ini.

Ketika @parallel berada 1 di sp_execute_external_script, nilai ini berkisar dari 0 hingga tingkat paralelisme kueri
RowsNumber Output Jumlah pasangan kunci-nilai
CounterNames Output Data string yang berisi kunci
CounterNamesLength Output Panjang setiap string kunci
CounterValues Output Data bilangan bulat 64-bit yang berisi nilai

InstallExternalLibrary

Menginstal pustaka. Fungsi ini bersifat opsional dan tidak memerlukan implementasi. Implementasi default adalah menyalin konten pustaka (lihat CREATE EXTERNAL LIBRARY) ke file di lokasi yang tepat. Nama file adalah nama pustaka.

Sintaks

SQLRETURN InstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryFile,
    SQLINTEGER LibraryFileLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

Argumen

Argumen Input/output Deskripsi
SetupSessionId Input GUID secara unik mengidentifikasi sesi skrip ini
LibraryName Input Nama pustaka
LibraryNameLength Input Panjang nama pustaka
LibraryFile Input Jalur (sebagai string) ke file pustaka yang berisi konten biner yang ditentukan oleh CREATE EXTERNAL LIBRARY
LibraryFileLength Input Panjang LibraryFile string
LibraryInstallDirectory Input Direktori akar untuk menginstal pustaka
LibraryInstallDirectoryLength Input Panjang LibraryInstallDirectory string
LibraryError Output Parameter output opsional. Jika ada kesalahan selama penginstalan pustaka, LibraryError arahkan ke string yang menjelaskan kesalahan
LibraryErrorLength Output Panjang LibraryError string

UninstallExternalLibrary

Menghapus instalasi pustaka. Fungsi ini bersifat opsional dan tidak memerlukan implementasi. Implementasi default adalah untuk membatalkan pekerjaan yang dilakukan oleh implementasi default .InstallExternalLibrary Implementasi default menghapus konten file di LibraryName bawah LibraryInstallDirectory.

Sintaks

SQLRETURN UninstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

Argumen

Argumen Input/output Deskripsi
SetupSessionId Input GUID secara unik mengidentifikasi sesi skrip ini
LibraryName Input Nama pustaka
LibraryNameLength Input Panjang nama pustaka
LibraryFile Input Jalur (sebagai string) ke file pustaka yang berisi konten biner yang ditentukan oleh CREATE EXTERNAL LIBRARY
LibraryFileLength Input Panjang LibraryFile string
LibraryInstallDirectory Input Direktori akar untuk menginstal pustaka
LibraryInstallDirectoryLength Input Panjang LibraryInstallDirectory string
LibraryError Output String kesalahan pustaka
LibraryErrorLength Output Panjang LibraryError string