Document and add an example.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@179003 c90b9560-bf6c-de11-be94-00142212c4b1

reference/pdo/functions/PDO-getAttribute.xml

@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
 <refentry id="function.PDO-getAttribute">
  <refnamediv>
   <refname>PDO::getAttribute</refname>
   <refpurpose>
-   Retrive a database connection attribute
+   Retrieve a database connection attribute
   </refpurpose>
  </refnamediv>
  <refsect1 role="description">
@@ -15,66 +15,115 @@
    <methodparam><type>long</type><parameter>attribute</parameter></methodparam>
   </methodsynopsis>
 
-  &warn.undocumented.func;
+  &warn.experimental.func;
+
+  <para>
+   This function returns the value of a database connection attribute. To
+   retrieve PDOStatement attributes, refer to
+   <function>PDOStatement::getAttribute</function>.
+  </para>
+
+  <para>
+   Note that some databases may not support all of the database connection
+   attributes.
+  </para>
 
  </refsect1>
 
- <!--
  <refsect1 role="parameters">
   &reftitle.parameters;
   <para>
    <variablelist>
     <varlistentry>
      <term><parameter>attribute</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
+     <listitem>
+      <para>
+       One of the <literal>PDO_ATTR_*</literal> constants. The constants that
+       apply to database connections are as follows:
+       <simplelist> 
+        <member><literal>PDO_ATTR_AUTOCOMMIT</literal></member>
+        <member><literal>PDO_ATTR_CASE</literal></member>
+        <member><literal>PDO_ATTR_CLIENT_VERSION</literal></member>
+        <member><literal>PDO_ATTR_CONNECTION_STATUS</literal></member>
+        <member><literal>PDO_ATTR_ERRMODE</literal></member>
+        <member><literal>PDO_ATTR_ORACLE_NULLS</literal></member>
+        <member><literal>PDO_ATTR_PERSISTENT</literal></member>
+        <member><literal>PDO_ATTR_PREFETCH</literal></member>
+        <member><literal>PDO_ATTR_SERVER_INFO</literal></member>
+        <member><literal>PDO_ATTR_SERVER_VERSION</literal></member>
+        <member><literal>PDO_ATTR_TIMEOUT</literal></member>
+       </simplelist> 
+      </para>
+     </listitem>
      </varlistentry>
    </variablelist>
   </para>
  </refsect1>
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   What the function returns, first on success, then on failure. See
-   also the &return.success; entity
+   A successful call returns the value of the requested PDO attribute.
+   An unsuccessfull call returns <literal>null</literal>.
   </para>
  </refsect1>
- -->
 
- <!-- Use when examples exist
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title><function>A PDO-getAttribute example</title>
-    <para>
-     Any text that describes the purpose of the example, or
-     what goes on in the example should go here (inside the
-     <example> tag, not out
-    </para>
+    <title>Retrieving database connection attributes</title>
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($anexample === true) {
-    echo 'Use the PEAR Coding Standards';
-}
+$conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
+
+print "\nPDO_ATTR_AUTOCOMMIT: ";
+print $conn->getAttribute(PDO_ATTR_AUTOCOMMIT);
+
+print "\nPDO_ATTR_ERRMODE: ";
+print $conn->getAttribute(PDO_ATTR_ERRMODE);
+
+print "\nPDO_ATTR_CASE: ";
+print $conn->getAttribute(PDO_ATTR_CASE);
+
+print "\nPDO_ATTR_CLIENT_VERSION: ";
+print $conn->getAttribute(PDO_ATTR_CLIENT_VERSION);
+
+print "\nPDO_ATTR_CONNECTION_STATUS: ";
+print $conn->getAttribute(PDO_ATTR_CONNECTION_STATUS);
+
+print "\nPDO_ATTR_ORACLE_NULLS: ";
+print $conn->getAttribute(PDO_ATTR_ORACLE_NULLS);
+
+print "\nPDO_ATTR_PERSISTENT: ";
+print $conn->getAttribute(PDO_ATTR_PERSISTENT);
+
+print "\nPDO_ATTR_PREFETCH: ";
+print $conn->getAttribute(PDO_ATTR_PREFETCH);
+
+print "\nPDO_ATTR_SERVER_INFO: ";
+print $conn->getAttribute(PDO_ATTR_SERVER_INFO);
+
+print "\nPDO_ATTR_SERVER_VERSION: ";
+print $conn->getAttribute(PDO_ATTR_SERVER_VERSION);
+
+print "\nPDO_ATTR_TIMEOUT: ";
+print $conn->getAttribute(PDO_ATTR_TIMEOUT);
 ?>
 ]]>
     </programlisting>
+    <!--
     &example.outputs;
     <screen>
 <![CDATA[
 Use the PEAR Coding Standards
 ]]>
     </screen>
+    -->
    </example>
   </para>
  </refsect1>
- -->
-
 
  <refsect1 role="seealso">
   &reftitle.seealso;