sqlsrv_prepare

Artikel
01/10/2024

Membuat sumber daya pernyataan yang terkait dengan koneksi yang ditentukan. Fungsi ini berguna untuk eksekusi beberapa kueri.

Sintaks

  
sqlsrv_prepare(resource $conn, string $tsql [, array $params [, array $options]])

Parameter

$conn: Sumber daya koneksi yang terkait dengan pernyataan yang dibuat.

$tsql: Ekspresi Transact-SQL yang sesuai dengan pernyataan yang dibuat.

$params [OPSIONAL]: Array nilai yang sesuai dengan parameter dalam kueri berparameter. Setiap elemen array dapat berupa salah satu dari berikut ini:

Nilai harfiah.
Referensi ke variabel PHP.

Array dengan struktur berikut:

array(&$value [, $direction [, $phpType [, $sqlType]]])

Catatan

Variabel yang diteruskan sebagai parameter kueri harus diteruskan oleh referensi alih-alih berdasarkan nilai. Misalnya, teruskan &$myVariable alih-alih $myVariable. Peringatan PHP dimunculkan saat kueri dengan parameter menurut nilai dijalankan.

Tabel berikut ini menjelaskan elemen array ini:

Elemen	Deskripsi
&$value	Nilai harfiah atau referensi ke variabel PHP.
$direction[OPSIONAL]	Salah satu konstanta SQLSRV_PARAM_* berikut yang digunakan untuk menunjukkan arah parameter: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. Nilai defaultnya adalah SQLSRV_PARAM_IN. Untuk informasi selengkapnya tentang konstanta PHP, lihat Konstanta (Driver Microsoft untuk PHP untuk SQL Server).
$phpType[OPSIONAL]	Konstanta SQLSRV_PHPTYPE_* yang menentukan jenis data PHP dari nilai yang dikembalikan.
$sqlType[OPSIONAL]	Konstanta SQLSRV_SQLTYPE_* yang menentukan jenis data SQL Server dari nilai input.

$options [OPSIONAL]: Array asosiatif yang mengatur properti kueri. Tabel berikut mencantumkan kunci yang didukung dan nilai terkait:

Tombol	Nilai yang Didukung	Deskripsi
ClientBufferMaxKBSize	Bilangan bulat positif	Mengonfigurasi ukuran buffer yang menyimpan hasil yang ditetapkan untuk kursor sisi klien. Defaultnya adalah 10240 KB. Untuk informasi selengkapnya, baca Menentukan Tipe Kursor dan Memilih Baris.
DecimalPlaces	Bilangan bulat antara 0 dan 4 (inklusif)	Menentukan tempat desimal saat memformat nilai uang yang diambil. Bilangan bulat atau nilai negatif apa pun lebih dari 4 akan diabaikan. Opsi ini hanya berfungsi ketika FormatDecimals benar.
FormatDecimals	benar atau salah Nilai default-nya adalah salah.	Menentukan apakah akan menambahkan nol di depan ke string desimal jika sesuai dan mengaktifkan `DecimalPlaces` opsi untuk memformat jenis uang. Untuk informasi selengkapnya, lihat Memformat String Desimal dan Nilai Uang (Driver SQLSRV).
QueryTimeout	Bilangan bulat positif	Mengatur batas waktu kueri dalam detik. Secara default, driver menunggu tanpa batas waktu untuk hasil.
ReturnDatesAsStrings	benar atau salah Nilai default-nya adalah salah.	Mengonfigurasi pernyataan untuk mengambil jenis tanggal dan waktu sebagai string (true). Untuk informasi selengkapnya, baca Cara: Mengambil Jenis Tanggal dan Waktu sebagai String Menggunakan Driver SQLSRV.
Digulir	SQLSRV_CURSOR_FORWARD SQLSRV_CURSOR_STATIC SQLSRV_CURSOR_DYNAMIC SQLSRV_CURSOR_KEYSET SQLSRV_CURSOR_CLIENT_BUFFERED	Untuk informasi selengkapnya tentang nilai-nilai ini, lihat Menentukan Jenis Kursor dan Memilih Baris.
SendStreamParamsAtExec	benar atau salah Nilai defaultnya adalah benar.	Mengonfigurasi driver untuk mengirim semua data aliran saat eksekusi (benar), atau untuk mengirim data aliran dalam gugus (false). Secara default, nilai diatur ke true. Untuk informasi selengkapnya, lihat sqlsrv_send_stream_data.

Tampilkan Nilai

Sumber daya pernyataan. Jika sumber daya pernyataan tidak dapat dibuat, false akan dikembalikan.

Keterangan

Saat Anda menyiapkan pernyataan yang menggunakan variabel sebagai parameter, variabel terikat ke pernyataan. Itu berarti bahwa jika Anda memperbarui nilai variabel, saat berikutnya Anda menjalankan pernyataan, itu akan berjalan dengan nilai parameter yang diperbarui.

Kombinasi sqlsrv_prepare dan sqlsrv_execute memisahkan persiapan pernyataan dan eksekusi pernyataan dalam dua panggilan fungsi dan dapat digunakan untuk menjalankan kueri berparameter. Fungsi ini sangat ideal untuk menjalankan pernyataan beberapa kali dengan nilai parameter yang berbeda untuk setiap eksekusi.

Untuk strategi alternatif untuk menulis dan membaca informasi dalam jumlah besar, lihat Batch Pernyataan SQL dan SISIPAN MASSAL.

Untuk informasi selengkapnya, lihat Cara: Mengambil Parameter Output Menggunakan Driver SQLSRV.

Contoh 1

Contoh berikut menyiapkan dan menjalankan pernyataan. Pernyataan, saat dijalankan (lihat sqlsrv_execute), memperbarui bidang di tabel Sales.SalesOrderDetail database AdventureWorks. Contoh mengasumsikan bahwa SQL Server dan database AdventureWorks diinstal di komputer lokal. Semua output ditulis ke konsol saat contoh dijalankan dari baris perintah.

<?php  
/* Connect to the local server using Windows Authentication and  
specify the AdventureWorks database as the database in use. */  
$serverName = "(local)";  
$connectionInfo = array("Database"=>"AdventureWorks");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
    echo "Could not connect.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Set up Transact-SQL query. */  
$tsql = "UPDATE Sales.SalesOrderDetail   
         SET OrderQty = ?   
         WHERE SalesOrderDetailID = ?";  
  
/* Assign parameter values. */  
$param1 = 5;  
$param2 = 10;  
$params = array(&$param1, &$param2);  
  
/* Prepare the statement. */  
if ($stmt = sqlsrv_prepare($conn, $tsql, $params)) {
    echo "Statement prepared.\n";  
} else {  
    echo "Statement could not be prepared.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Execute the statement. */  
if (sqlsrv_execute($stmt)) {  
    echo "Statement executed.\n";  
} else {  
    echo "Statement could not be executed.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Free the statement and connection resources. */  
sqlsrv_free_stmt($stmt);  
sqlsrv_close($conn);  
?>

Contoh 2

Contoh berikut menunjukkan cara menyiapkan pernyataan lalu menjalankannya kembali dengan nilai parameter yang berbeda. Contoh memperbarui kolom OrderQty dari tabel Sales.SalesOrderDetail di database AdventureWorks. Setelah pembaruan terjadi, database dikueri untuk memverifikasi bahwa pembaruan berhasil. Contoh mengasumsikan bahwa SQL Server dan database AdventureWorks diinstal di komputer lokal. Semua output ditulis ke konsol saat contoh dijalankan dari baris perintah.

<?php  
/* Connect to the local server using Windows Authentication and  
specify the AdventureWorks database as the database in use. */  
$serverName = "(local)";  
$connectionInfo = array("Database"=>"AdventureWorks");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
     echo "Could not connect.\n";  
     die(print_r(sqlsrv_errors(), true));  
}  
  
/* Define the parameterized query. */  
$tsql = "UPDATE Sales.SalesOrderDetail  
         SET OrderQty = ?  
         WHERE SalesOrderDetailID = ?";  
  
/* Initialize parameters and prepare the statement. Variables $qty  
and $id are bound to the statement, $stmt1. */  
$qty = 0; $id = 0;  
$stmt1 = sqlsrv_prepare($conn, $tsql, array(&$qty, &$id));  
if ($stmt1) {  
    echo "Statement 1 prepared.\n";  
} else {  
    echo "Error in statement preparation.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Set up the SalesOrderDetailID and OrderQty information. This array  
maps the order ID to order quantity in key=>value pairs. */  
$orders = array(1=>10, 2=>20, 3=>30);  
  
/* Execute the statement for each order. */  
foreach ($orders as $id => $qty) {  
    // Because $id and $qty are bound to $stmt1, their updated  
    // values are used with each execution of the statement.   
    if (sqlsrv_execute($stmt1) === false) {  
        echo "Error in statement execution.\n";  
        die(print_r(sqlsrv_errors(), true));  
    }  
}  
echo "Orders updated.\n";  
  
/* Free $stmt1 resources.  This allows $id and $qty to be bound to a different statement.*/  
sqlsrv_free_stmt($stmt1);  
  
/* Now verify that the results were successfully written by selecting   
the newly inserted rows. */  
$tsql = "SELECT OrderQty   
         FROM Sales.SalesOrderDetail   
         WHERE SalesOrderDetailID = ?";  
  
/* Prepare the statement. Variable $id is bound to $stmt2. */  
$stmt2 = sqlsrv_prepare($conn, $tsql, array(&$id));  
if ($stmt2) {  
    echo "Statement 2 prepared.\n";  
} else {  
    echo "Error in statement preparation.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  
  
/* Execute the statement for each order. */  
foreach (array_keys($orders) as $id)  
{  
    /* Because $id is bound to $stmt2, its updated value   
    is used with each execution of the statement. */  
    if (sqlsrv_execute($stmt2)) {  
        sqlsrv_fetch($stmt2);  
        $quantity = sqlsrv_get_field($stmt2, 0);  
        echo "Order $id is for $quantity units.\n";  
    } else {  
        echo "Error in statement execution.\n";  
        die(print_r(sqlsrv_errors(), true));  
    }  
}  
  
/* Free $stmt2 and connection resources. */  
sqlsrv_free_stmt($stmt2);  
sqlsrv_close($conn);  
?>

Catatan

Disarankan untuk menggunakan string sebagai input saat mengikat nilai ke kolom desimal atau numerik untuk memastikan presisi dan akurasi karena PHP memiliki presisi terbatas untuk angka titik float. Hal yang sama berlaku untuk kolom bigint, terutama ketika nilai berada di luar rentang bilangan bulat.

Contoh 3

Sampel kode ini menunjukkan cara mengikat nilai desimal sebagai parameter input.

<?php
$serverName = "(local)";
$connectionInfo = array("Database"=>"YourTestDB");  
$conn = sqlsrv_connect($serverName, $connectionInfo);  
if ($conn === false) {  
    echo "Could not connect.\n";  
    die(print_r(sqlsrv_errors(), true));  
}  

// Assume TestTable exists with a decimal field 
$input = "9223372036854.80000";
$params = array($input);
$stmt = sqlsrv_prepare($conn, "INSERT INTO TestTable (DecimalCol) VALUES (?)", $params);
sqlsrv_execute($stmt);

sqlsrv_free_stmt($stmt);  
sqlsrv_close($conn);  

?>