sqlsrv_prepare

Crea un recurso de la instrucción asociado con la conexión especificada.

Nota

Esta función es ideal cuando se ejecutan varias consultas. Para obtener más información, vea Cómo ejecutar una consulta varias veces.

Sintaxis

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

Parámetros

$conn: el recurso de conexión asociado con la instrucción creada.

$tsql: la expresión de Transact-SQL que corresponde a la instrucción creada.

$params [OPCIONAL]: una matriz (array) de valores que se corresponden con los parámetros de una consulta con parámetros. Los elementos de la matriz pueden ser cualquiera de los siguientes:

• Un valor literal.

• Una referencia a una variable PHP.

• Una matriz (array) con la estructura siguiente:

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

  Nota

  Las variables que se pasan como parámetros de consulta se deben pasar por referencia en lugar de por valor. Por ejemplo, pase &$myVariable en lugar de $myVariable. PHP mostrará una advertencia cuando se ejecute una consulta con parámetros por valor.

  En la siguiente tabla se describen estos elementos de la matriz:

  Elemento	Descripción
  &$value	Un valor literal o una referencia a una variable de PHP.
  $direction[OPCIONAL]	Una de las siguientes constantes de SQLSRV_PARAM_* se usan para indicar la dirección del parámetro: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. El valor predeterminado es SQLSRV_PARAM_IN.
  $phpType[OPCIONAL]	Una constante SQLSRV_PHPTYPE_* que especifica el tipo de datos de PHP del valor devuelto.
  $sqlType[OPCIONAL]	Una constante SQLSRV_SQLTYPE_* que especifica el tipo de datos de SQL Server del valor de entrada.

$options [OPCIONAL]: una matriz asociativa que establece las propiedades de la consulta. En la siguiente tabla se muestran las claves y sus correspondientes valores admitidos:

Clave	Valores admitidos	Descripción
QueryTimeout	Un valor entero positivo.	Establece el tiempo de espera de la consulta en segundos. De forma predeterminada, el controlador esperará indefinidamente los resultados.
SendStreamParamsAtExec	true o false El valor predeterminado es true.	Configura el controlador para que envíe todos los datos en secuencias en el momento de la ejecución (true) o para que envíe los datos en secuencias en fragmentos (false). De forma predeterminada, el valor está establecido en true. Para obtener más información, vea sqlsrv_send_stream_data.
De desplazamiento	SQLSRV_CURSOR_FORWARD SQLSRV_CURSOR_STATIC SQLSRV_CURSOR_DYNAMIC SQLSRV_CURSOR_KEYSET	Esta clave se ha agregado en la versión 1.1 del Controlador de SQL Server para PHP. Para obtener más información acerca de estos valores, vea Especificar un tipo de cursor y seleccionar filas.

Valor devuelto

Un recurso de instrucción. Si no se puede crear el recurso de instrucción, se devuelve false.

Ejemplo

En el siguiente ejemplo se prepara y se ejecuta una instrucción. Cuando se ejecuta la instrucción (vea sqlsrv_execute), se actualiza un campo de la tabla Sales.SalesOrderDetail de la base de datos AdventureWorks. En el ejemplo se supone que SQL Server y la base de datos AdventureWorks están instalados en el equipo local. Cuando se ejecuta el ejemplo desde la línea de comandos, todos los resultados se escriben en la consola.

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

Vea también

Tareas

Cómo realizar consultas parametrizadas
Cómo enviar datos como una secuencia

Conceptos

Acerca de ejemplos de código en la documentación

Otros recursos

Referencia de la API (Controlador SQL Server para PHP)
Consideraciones de diseño
Usar parámetros de direcciones