steinm Thu Mar 30 15:53:42 2006 UTC
Modified files:
/phpdoc/en/reference/paradox/functions px-insert-record.xml
Log:
- added much more documentation including an example
http://cvs.php.net/viewcvs.cgi/phpdoc/en/reference/paradox/functions/px-insert-record.xml?r1=1.1&r2=1.2&diff_format=u
Index: phpdoc/en/reference/paradox/functions/px-insert-record.xml
diff -u phpdoc/en/reference/paradox/functions/px-insert-record.xml:1.1
phpdoc/en/reference/paradox/functions/px-insert-record.xml:1.2
--- phpdoc/en/reference/paradox/functions/px-insert-record.xml:1.1 Wed Feb
8 06:34:54 2006
+++ phpdoc/en/reference/paradox/functions/px-insert-record.xml Thu Mar 30
15:53:42 2006
@@ -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 >= 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
