php-doc-en/reference/sqlsrv/functions/sqlsrv-query.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.sqlsrv-query" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>sqlsrv_query</refname>
  <refpurpose>Prepares and executes a query.</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>sqlsrv_query</methodname>
   <methodparam><type>resource</type><parameter>conn</parameter></methodparam>
   <methodparam><type>string</type><parameter>sql</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>params</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter>options</parameter></methodparam>
  </methodsynopsis>
  <para>
   Prepares and executes a query.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>conn</parameter></term>
     <listitem>
      <para>
       A connection resource returned by <function>sqlsrv_connect</function>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>sql</parameter></term>
     <listitem>
      <para>
       The string that defines the query to be prepared and executed.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>params</parameter></term>
     <listitem>
      <para>
       An array specifying parameter information when executing a parameterized query. 
       Array elements can be any of the following:
       <simplelist>
        <member>A literal value</member>
        <member>A PHP variable</member>
        <member>An array with this structure: 
        array($value [, $direction [, $phpType [, $sqlType]]])</member>
       </simplelist>
       The following table describes the elements in the array structure above:
       </para>
       <table>
       <title>Array structure</title>
       <tgroup cols="2">
        <thead>
         <row>
          <entry>Element</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>$value</entry>
          <entry>A literal value, a PHP variable, or a PHP by-reference variable.</entry>
         </row>
         <row>
          <entry>$direction (optional)</entry>
          <entry>One of the following SQLSRV constants used to indicate the 
          parameter direction: SQLSRV_PARAM_IN, SQLSRV_PARAM_OUT, SQLSRV_PARAM_INOUT. 
          The default value is SQLSRV_PARAM_IN.</entry>
         </row>
         <row>
          <entry>$phpType (optional)</entry>
          <entry>A SQLSRV_PHPTYPE_* constant that specifies PHP data type of the 
          returned value.</entry>
         </row>
         <row>
          <entry>$sqlType (optional)</entry>
          <entry>A SQLSRV_SQLTYPE_* constant that specifies the SQL Server data 
          type of the input value.</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>options</parameter></term>
     <listitem>
      <para>
       An array specifing query property options. The supported keys are described 
       in the following table:
      </para>
      <table>
       <title>Query Options</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Key</entry>
          <entry>Values</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>QueryTimeout</entry>
          <entry>A positive integer value.</entry>
          <entry>Sets the query timeout in seconds. By default, the driver will 
          wait indefinitely for results.</entry>
         </row>
         <row>
          <entry>SendStreamParamsAtExec</entry>
          <entry>&true; or &false; (the default is &true;)</entry>
          <entry>Configures the driver to send all stream data at execution (&true;), 
          or to send stream data in chunks (&false;). By default, the value is set 
          to &true;. For more information, see <function>sqlsrv_send_stream_data</function>.</entry>
         </row>
         <row>
          <entry>Scrollable</entry>
          <entry>SQLSRV_CURSOR_FORWARD, SQLSRV_CURSOR_STATIC, SQLSRV_CURSOR_DYNAMIC, 
          or SQLSRV_CURSOR_KEYSET</entry>
          <entry>See <link xlink:href="&url.sqlsrv.specify.cursortype;">Specifying 
          a Cursor Type and Selecting Rows</link> in the Microsoft SQLSRV documentation.</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a statement resource on success and &false; if an error occurred.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>sqlsrv_query</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$serverName = "serverName\sqlexpress";
$connectionInfo = array( "Database"=>"dbName", "UID"=>"username", "PWD"=>"password" );
$conn = sqlsrv_connect( $serverName, $connectionInfo);
if( $conn === false ) {
     die( print_r( sqlsrv_errors(), true));
}

$sql = "INSERT INTO Table_1 (id, data) VALUES (?, ?)";
$params = array(1, "some data");

$stmt = sqlsrv_query( $conn, $sql, $params);
if( $stmt === false ) {
     die( print_r( sqlsrv_errors(), true));
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <para>
   For statements that you plan to execute only once, use <function>sqlsrv_query</function>. 
   If you intend to re-execute a statement with different parameter values, use 
   the combination of <function>sqlsrv_prepare</function> and <function>sqlsrv_execute</function>.
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlsrv_prepare</function></member>
    <member><function>sqlsrv_execute</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->