sqlsrv_prepare

아티클
01/10/2024

지정된 연결과 연결된 문 리소스를 만듭니다. 이 함수는 여러 쿼리를 실행하는 데 유용합니다.

구문

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

매개 변수

$conn: 만든 문과 연결된 연결 리소스입니다.

$tsql: 만든 문에 해당하는 Transact-SQL 식입니다.

$params [OPTIONAL]: 매개 변수가 있는 쿼리의 매개 변수에 해당하는 값 배열입니다. 배열의 각 요소는 다음 중 하나일 수 있습니다.

리터럴 값.
PHP 변수에 대한 참조입니다.

다음 구조가 있는 배열입니다.

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

참고 항목

쿼리 매개 변수로 전달된 변수는 값 대신 참조로 전달되어야 합니다. 예를 들어 . 대신 전달 &$myVariable 합니다 $myVariable. 값별 매개 변수가 있는 쿼리가 실행될 때 PHP 경고가 발생합니다.

다음 표에서는 이러한 배열 요소에 대해 설명합니다.

요소	설명
&$value	리터럴 값 또는 PHP 변수에 대한 참조입니다.
$direction[선택 사항]	매개 변수 방향을 나타내는 데 사용되는 SQLSRV_PARAM_* 상수인 SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT 중 하나입니다. 기본값은 SQLSRV_PARAM_IN입니다. PHP 상수에 대한 자세한 내용은 상수(Microsoft Drivers for PHP for SQL Server)를 참조하세요.
$phpType[선택 사항]	반환된 값의 PHP 데이터 형식을 지정하는 SQLSRV_PHPTYPE_* 상수입니다.
$sqlType[선택 사항]	입력 값의 SQL Server 데이터 형식을 지정하는 SQLSRV_SQLTYPE_* 상수입니다.

$options [OPTIONAL]: 쿼리 속성을 설정하는 결합형 배열입니다. 다음 표에서는 지원되는 키와 해당 값을 나열합니다.

키	지원되는 값	설명
ClientBufferMaxKBSize	양의 정수	클라이언트 쪽 커서에 대한 결과 집합을 보유하는 버퍼의 크기를 구성합니다. 기본값은 10240KB입니다. 자세한 내용은 커서 유형 지정 및 행 선택을 참조하세요.
DecimalPlaces	0에서 4 사이의 정수(포함)	인출된 금액 값의 서식을 지정할 때 소수 자릿수를 지정합니다. 4보다 큰 음수 정수 또는 값은 무시됩니다. 이 옵션은 FormatDecimals가 true인 경우에만 작동합니다.
FormatDecimals	true 또는 false 기본값은 false입니다.	해당하는 경우 10진수 문자열에 앞에 오는 0을 추가할지 여부를 지정하고 money 형식의 서식을 지정하기 위한 `DecimalPlaces` 옵션을 사용하도록 설정합니다. 자세한 내용은 10진수 문자열 및 금액 값 서식 지정(SQLSRV 드라이버)을 참조하세요.
QueryTimeout	양의 정수	쿼리 시간 제한을 초 단위로 설정합니다. 기본적으로 드라이버는 결과를 무기한 대기합니다.
ReturnDatesAsStrings	true 또는 false 기본값은 false입니다.	날짜 및 시간 형식을 문자열로 검색하도록 문을 구성합니다(true). 자세한 내용은 방법: SQLSRV 드라이버를 사용하여 날짜 및 시간 형식을 문자열로 검색합니다.
스크롤 가능	SQLSRV_CURSOR_FORWARD SQLSRV_CURSOR_STATIC SQLSRV_CURSOR_DYNAMIC SQLSRV_CURSOR_KEYSET SQLSRV_CURSOR_CLIENT_BUFFERED	이러한 값에 대한 자세한 내용은 커서 유형 지정 및 행 선택을 참조하세요.
SendStreamParamsAtExec	true 또는 false 기본값은 true입니다.	실행 시 모든 스트림 데이터를 보내거나(true) 스트림 데이터를 청크로 보내도록(false) 드라이버를 구성합니다. 기본적으로 값은 true로 설정됩니다. 자세한 내용은 sqlsrv_send_stream_data 참조하세요.

Return Value

문 리소스입니다. 문 리소스를 만들 수 없는 경우 false 가 반환됩니다.

설명

변수를 매개 변수로 사용하는 문을 준비하면 변수가 문에 바인딩됩니다. 즉, 변수 값을 업데이트하는 경우 다음에 문을 실행할 때 업데이트된 매개 변수 값으로 실행됩니다.

sqlsrv_prepare 및 sqlsrv_execute 조합은 문 준비와 문 실행을 두 함수 호출로 구분하고 매개 변수가 있는 쿼리를 실행하는 데 사용할 수 있습니다. 이 함수는 각 실행에 대해 서로 다른 매개 변수 값을 사용하여 문을 여러 번 실행하는 데 적합합니다.

많은 양의 정보를 작성하고 읽기 위한 대체 전략은 SQL 문 일괄 처리 및 BULK INSERT를 참조하세요.

자세한 내용은 방법: SQLSRV 드라이버를 사용하여 출력 매개 변수 검색을 참조하세요.

예 1

다음 예제에서는 문을 준비하고 실행합니다. 명령문은 실행될 때(sqlsrv_execute 참조) AdventureWorks 데이터베이스의 Sales.SalesOrderDetail 테이블에서 필드를 업데이트합니다. 이 예제에서는 SQL Server 및 AdventureWorks 데이터베이스가 로컬 컴퓨터에 설치되어 있다고 가정합니다. 모든 출력은 명령줄에서 예제가 실행될 때 콘솔에 기록됩니다.

<?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);  
?>

예제 2

다음 예제에서는 문을 준비한 다음 다른 매개 변수 값으로 다시 실행하는 방법을 보여 줍니다. 이 예제에서는 AdventureWorks 데이터베이스에서 Sales.SalesOrderDetail 테이블의 OrderQty 열을 업데이트합니다. 업데이트가 발생한 후 업데이트가 성공했는지 확인하기 위해 데이터베이스가 쿼리됩니다. 이 예제에서는 SQL Server 및 AdventureWorks 데이터베이스가 로컬 컴퓨터에 설치되어 있다고 가정합니다. 모든 출력은 명령줄에서 예제가 실행될 때 콘솔에 기록됩니다.

<?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);  
?>

참고 항목

PHP에서는 부동 소수점 숫자의 정밀도가 제한되어 있으므로 decimal 또는 numeric 열에 값을 바인딩할 때는 정밀도와 정확도를 보장하기 위해 문자열을 입력으로 사용하는 것이 좋습니다. 특히 값이 정수 범위를 벗어난 경우 bigint 열에도 동일하게 적용됩니다.

예 3

이 코드 샘플에서는 10진수 값을 입력 매개 변수로 바인딩하는 방법을 보여줍니다.

<?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);  

?>