From c8c9653b23c89a527bcd2e7ffc9ae60e2d884827 Mon Sep 17 00:00:00 2001
From: Kalle Sommer Nielsen <kalle@php.net>
Date: Tue, 7 Oct 2008 02:34:38 +0000
Subject: [PATCH] Part 1/2 of updates to MSSQL docs  - Documented the following
 functions   - mssql_rows_affected   - mssql_guid_string  - Added examples for
 the following functions   - mssql_close   - mssql_connect   - mssql_num_rows 
  - mssql_query   - mssql_rows_affected   - mssql_select_db  - State that the
 following function parameter types has changed   - mssql_bind    - is_output
 and is_null is booleans   - mssql_guid_string    - short_Format is boolean

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@267030 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mssql/functions/mssql-bind.xml      |  6 +--
 reference/mssql/functions/mssql-close.xml     | 24 +++++++++++-
 reference/mssql/functions/mssql-connect.xml   | 26 ++++++++++++-
 .../mssql/functions/mssql-guid-string.xml     | 39 +++++++++++++++++--
 reference/mssql/functions/mssql-num-rows.xml  | 28 ++++++++++++-
 reference/mssql/functions/mssql-query.xml     | 30 +++++++++++++-
 .../mssql/functions/mssql-rows-affected.xml   | 34 ++++++++++++++--
 reference/mssql/functions/mssql-select-db.xml |  9 +++--
 8 files changed, 178 insertions(+), 18 deletions(-)

diff --git a/reference/mssql/functions/mssql-bind.xml b/reference/mssql/functions/mssql-bind.xml
index 6e91c90819..d3d80191cc 100644
--- a/reference/mssql/functions/mssql-bind.xml
+++ b/reference/mssql/functions/mssql-bind.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
 <refentry xml:id='function.mssql-bind' xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_bind</refname>
@@ -14,8 +14,8 @@
    <methodparam><type>string</type><parameter>param_name</parameter></methodparam>
    <methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
    <methodparam><type>int</type><parameter>type</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>is_output</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>is_null</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>is_output</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>is_null</parameter></methodparam>
    <methodparam choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam>
   </methodsynopsis>
   <para>
diff --git a/reference/mssql/functions/mssql-close.xml b/reference/mssql/functions/mssql-close.xml
index fa8fed44c1..7578efafbf 100644
--- a/reference/mssql/functions/mssql-close.xml
+++ b/reference/mssql/functions/mssql-close.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <refentry xml:id="function.mssql-close" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_close</refname>
@@ -52,6 +52,28 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>mssql_close</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Connect to MSSQL
+$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
+
+// Do any related operations here
+
+// Close the link to MSSQL
+mssql_close($link);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/mssql/functions/mssql-connect.xml b/reference/mssql/functions/mssql-connect.xml
index e989d2395c..54831e9443 100644
--- a/reference/mssql/functions/mssql-connect.xml
+++ b/reference/mssql/functions/mssql-connect.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.mssql-connect">
  <refnamediv>
   <refname>mssql_connect</refname>
@@ -104,6 +104,30 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>mssql_connect</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Server in the this format: <computer>\<instance name>
+$server = 'KALLESPC\SQLEXPRESS';
+
+$link = mssql_connect($server, 'sa', 'phpfi');
+
+if(!$link)
+{
+	die('Something went wrong while connecting to MSSQL');
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/mssql/functions/mssql-guid-string.xml b/reference/mssql/functions/mssql-guid-string.xml
index a37bd8647d..1cf6a68e14 100644
--- a/reference/mssql/functions/mssql-guid-string.xml
+++ b/reference/mssql/functions/mssql-guid-string.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry xml:id='function.mssql-guid-string' xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_guid_string</refname>
@@ -11,15 +11,46 @@
   <methodsynopsis>
    <type>string</type><methodname>mssql_guid_string</methodname>
    <methodparam><type>string</type><parameter>binary</parameter></methodparam>
-   <methodparam choice="opt"><type>int</type><parameter>short_format</parameter></methodparam>
+   <methodparam choice="opt"><type>bool</type><parameter>short_format</parameter></methodparam>
   </methodsynopsis>
+  <para>
+   Converts a 16 byte binary GUID to a string.
+  </para>
+ </refsect1>
 
-  &warn.undocumented.func;
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>binary</parameter></term>
+     <listitem>
+      <para>
+       A 16 byte binary GUID.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>short_format</parameter></term>
+     <listitem>
+      <para>
+       ...
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the converted string on success.
+  </para>
  </refsect1>
 
 </refentry>
-
+<
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
diff --git a/reference/mssql/functions/mssql-num-rows.xml b/reference/mssql/functions/mssql-num-rows.xml
index e154296444..5ce4d6cebe 100644
--- a/reference/mssql/functions/mssql-num-rows.xml
+++ b/reference/mssql/functions/mssql-num-rows.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <refentry xml:id="function.mssql-num-rows" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_num_rows</refname>
@@ -42,6 +42,32 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>mssql_num_rows</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Connect to MSSQL and select the database
+$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
+mssql_select_db('php');
+
+// Select all our records from a table
+$query = mssql_query('SELECT * FROM [php].[dbo].[persons]');
+
+echo 'Total records in database: ' . mssql_num_rows($query);
+
+// Clean up
+mssql_free_result($query);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
diff --git a/reference/mssql/functions/mssql-query.xml b/reference/mssql/functions/mssql-query.xml
index 7bcc0ed8f1..fcb4b14955 100644
--- a/reference/mssql/functions/mssql-query.xml
+++ b/reference/mssql/functions/mssql-query.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.11 $ -->
+<!-- $Revision: 1.12 $ -->
 <refentry xml:id="function.mssql-query" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_query</refname>
@@ -68,6 +68,34 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>mssql_query</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+// Connect to MSSQL
+$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi') or die('Unable to connect MSSQL');
+mssql_select_db('php', $link) or die('Unable to select database');
+
+// Do a simple query, select the version of 
+// MSSQL and print it.
+$version = mssql_query('SELECT @@VERSION');
+$row = mssql_fetch_array($version);
+
+echo $row[0];
+
+// Clean up
+mssql_free_result($version);
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="notes">
   &reftitle.notes;
   <note>
diff --git a/reference/mssql/functions/mssql-rows-affected.xml b/reference/mssql/functions/mssql-rows-affected.xml
index 929a28a5c5..0b862df247 100644
--- a/reference/mssql/functions/mssql-rows-affected.xml
+++ b/reference/mssql/functions/mssql-rows-affected.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
 <refentry xml:id='function.mssql-rows-affected' xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_rows_affected</refname>
@@ -12,9 +12,9 @@
    <type>int</type><methodname>mssql_rows_affected</methodname>
    <methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
   </methodsynopsis>
-
-   &warn.undocumented.func;
-
+  <para>
+   Returns the number of records affected by the last write query.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -35,6 +35,32 @@
   </para>
  </refsect1>
 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns the number of records affected by last operation.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>mssql_rows_affected</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php´
+// Delete all rows in a table
+mssql_query('TRUNCATE TABLE [php].[dbo].[persons]');
+
+echo 'Deleted ' . mssql_affected_rows($link) . ' row(s)';
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mssql/functions/mssql-select-db.xml b/reference/mssql/functions/mssql-select-db.xml
index 16d2dfde3b..6d62888b49 100644
--- a/reference/mssql/functions/mssql-select-db.xml
+++ b/reference/mssql/functions/mssql-select-db.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
 <refentry xml:id="function.mssql-select-db" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>mssql_select_db</refname>
@@ -77,8 +77,11 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$conn = mssql_connect('MYSQLSERVER', 'sa', 'password');
-mssql_select_db('[my data-base]', $conn);
+// Create a link to MSSQL
+$link = mssql_connect('KALLESPC\SQLEXPRESS', 'sa', 'phpfi');
+
+// Select the database 'php'
+mssql_select_db('php', $link);
 ?>
 ]]>
     </programlisting>