From 7990427082721b073c3b64967d945f71746b0b60 Mon Sep 17 00:00:00 2001
From: Christoph Michael Becker <cmb@php.net>
Date: Wed, 23 Sep 2020 12:02:23 +0000
Subject: [PATCH] odbc_data_source(): fix refpurpose and return values, and add
 example

This also integrates user note 37891.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@350619 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../uodbc/functions/odbc-data-source.xml      | 39 ++++++++++++++++++-
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/reference/uodbc/functions/odbc-data-source.xml b/reference/uodbc/functions/odbc-data-source.xml
index 7a1feeab0f..e11efacf6b 100644
--- a/reference/uodbc/functions/odbc-data-source.xml
+++ b/reference/uodbc/functions/odbc-data-source.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.odbc-data-source" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>odbc_data_source</refname>
-  <refpurpose>Returns information about a current connection</refpurpose>
+  <refpurpose>Returns information about available DSNs</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -44,9 +44,44 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns &false; on error, and an array upon success.
+   Returns &false; on error, an &array; upon success, and &null; after fetching
+   the last available DSN.
   </para>
  </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="odbc-data-source.example.basic">
+   <title>List available DSNs</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$conn = odbc_connect('dsn', 'user', 'pass');
+$dsn_info = odbc_data_source($conn, SQL_FETCH_FIRST);
+while ($dsn_info) {
+    print_r($dsn_info);
+    $dsn_info = odbc_data_source($conn, SQL_FETCH_NEXT);
+}
+?>
+]]>
+   </programlisting>
+   &example.outputs.similar;
+   <screen>
+<![CDATA[
+Array
+(
+    [server] => dsn
+    [description] => ODBC Driver 17 for SQL Server
+)
+Array
+(
+    [server] => other_dsn
+    [description] => Microsoft Access Driver (*.mdb, *.accdb)
+)]]>
+   </screen>
+  </example>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file