- added much more documentation including an example

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

reference/paradox/functions/px-insert-record.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- splitted from ./en/functions/paradox.xml, last change in rev  -->
 <refentry id="function.px-insert-record">
  <refnamediv>
@@ -14,6 +14,37 @@
    <methodparam><type>resource</type><parameter>pxdoc</parameter></methodparam>
    <methodparam><type>array</type><parameter>data</parameter></methodparam>
   </methodsynopsis>
+
+  <para>
+   Inserts a new record into the database. The record is not neccesarily
+   inserted at the end of the database, but may be inserted at any
+   position depending on where the first free slot is found.
+  </para>
+  <para>
+   The record data is passed as an array of field values. The elements in
+   the array must correspond to the fields in the database. If the array
+   has less elements than fields in the database, the remaining fields
+   will be set to null.
+  </para>
+  <para>
+   Most field values can be passed as its equivalent php type e.g. a long
+   value is used for fields of type PX_FIELD_LONG, PX_FIELD_SHORT and
+   PX_FIELD_AUTOINC, a double values is used for fields of type
+   PX_FIELD_CURRENCY and PX_FIELD_NUMBER.
+   Field values for blob and alpha fields are passed as strings.
+  </para>
+  <para>
+   Fields of type PX_FIELD_TIME and PX_FIELD_DATE both require a long
+   value. In the first case this is the number of milli seconds since
+   midnight. In the second case this is the number of days since 1.1.0000.
+   Below there are two examples to convert the current date or timestamp
+   into a value suitable for one of paradox's date/time fields.
+  </para>
+  <note>
+   <para>
+    This function is only available if pxlib &gt;= 0.6.0 is used.
+   </para>
+  </note>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -32,8 +63,8 @@
      <term><parameter>data</parameter></term>
      <listitem>
       <para>
-       Associated array containing the field values as returned by
-       <function>px_retrieve_record</function>.
+       Associated or indexed array containing the field values as e.g.
+       returned by <function>px_retrieve_record</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -57,6 +88,68 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Set the date/time fields in a paradox database to the current
+    date/time</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$px = px_new();
+$fp = fopen("test.db", "w+");
+px_create_fp($px, $fp, array(array("timestamp", "@"), array("time", "T"), array("date", "D")));
+
+$curdate = getdate();
+$jd = gregoriantojd($curdate["mon"], $curdate["mday"], $curdate["year"]);
+$days = $jd - 1721425; /* Number of days between 1.1.4714 b.c. and 1.1.0000 */
+$secs = $curdate["hours"]*3600 + $curdate["minutes"]*60 + $curdate["seconds"];
+px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));
+
+$curtimestamp = microtime(true);
+$days = (int) ($curtimestamp/86400);
+$secs = $curtimestamp - ($days * 86400.0);
+$days += 2440588; /* Number of days between 1.1.4914 b.c. and 1.1.1970 */
+$days -= 1721425; /* Number of days between 1.1.4914 b.c. and 1.1.0000 */
+px_insert_record($px, array($days*86400000.0 + $secs*1000.0, $secs*1000.0, $days));
+for($i=0; $i<2; $i++) {
+	$rec = px_retrieve_record($px, $i);
+	echo px_timestamp2string($px, $rec["timestamp"], "n/d/Y H:i:s")."\n";
+	echo px_date2string($px, $rec["date"], "n/d/Y")."\n";
+}
+px_close($px);
+px_delete($px);
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+2/21/2006 21:42:30
+2/21/2006
+2/21/2006 20:42:30
+2/21/2006
+]]>
+    </screen>
+   </example>
+  </para>
+
+  <para>
+    The julian day count as passed to <function>jdtogregorian</function>
+    has a different base of 1.1.4714 b.c. and must therefore be calculated
+    by adding 1721425 to the day count used in the paradox file. Turning the
+    day count into a timestamp is easily done by multiplying with 86400000.0
+    to optain milli seconds.
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+    <function>px_update_record</function>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file