From: <mie...@us...> - 2012-06-24 19:48:32
|
Revision: 7959 http://oorexx.svn.sourceforge.net/oorexx/?rev=7959&view=rev Author: miesfeld Date: 2012-06-24 19:48:26 +0000 (Sun, 24 Jun 2012) Log Message: ----------- Continue work on the ooSQLite documentation Modified Paths: -------------- docs/trunk/oosqlite/oosqliteConnection.xml Modified: docs/trunk/oosqlite/oosqliteConnection.xml =================================================================== --- docs/trunk/oosqlite/oosqliteConnection.xml 2012-06-23 23:34:54 UTC (rev 7958) +++ docs/trunk/oosqlite/oosqliteConnection.xml 2012-06-24 19:48:26 UTC (rev 7959) @@ -229,13 +229,13 @@ <indexterm><primary>ooSQLiteConnection class</primary><secondary>new</secondary></indexterm> <programlisting> <![CDATA[ ->>--new(--+--------+--)--------------------------------------------->< - +--type--+ +>>--new(--file--+---------+--+-------------+--+------------+--)---------------->< + +-,-opts--+ +-,-defFormat-+ +-,-reserved-+ ]]> </programlisting> <para> - xx + Instantiates a new database connection object and opens the specified database for use. </para> <variablelist> <varlistentry><term><emphasis role="bold">Arguments:</emphasis></term> @@ -243,40 +243,104 @@ <para> The arguments are: <variablelist> - <varlistentry><term>TERM</term> + <varlistentry><term>file [required]</term> <listitem> <para> - xx + The file name of the database to open. The special string <emphasis role="italic">:memory:</emphasis> can be + used to open an in memory database. The <emphasis role="italic">dbFileName</emphasis> argument can also be an + URI. Refer to the SQLite documentation for details. </para> </listitem></varlistentry> + <varlistentry><term>opts [optional]</term> + <listitem> + <para> + One or more of the file <link linkend="sctFileOpen">open</link> constants. This argument controls how the + database is opened. Do not use any constant marked as <emphasis role="italic">VFS only</emphasis>. Use the + <link linkend="mthMerge">merge</link> method of the <link + linkend="clsOOSQLiteConstants">ooSQLiteConstants</link> class to combine two or more of the constant values + together, if needed. + </para> + <para> + The 3 common flags are OPEN_READWRITE, OPEN_READONLY, and OPEN_CREATE. If this argument is omitted, the + OPEN_READWRITE combined with OPEN_CREATE flags are used. + </para> + </listitem></varlistentry> + <varlistentry><term>defFormat [optional]</term> + <listitem> + <para> + Specifies one of the ooSQLite Result Set Format <link linkend="sctOOSQLiteSpecific">Constants</link> that define + how a result set is formatted and sets the <link linkend="atrRecordFormatClsConn">recordFormat</link> attribute + for this database connection. This is a convenience argument, the <emphasis + role="italic">recordFormat</emphasis> attribute can always be set directly. If this argument is omitted, then + the <emphasis role="italic">recordFormat</emphasis> attribute is set to the value of the + <computeroutput>ooSQLite</computeroutput> class <link linkend="atrRecordFormatClsOOSQLite">recordFormat</link> + attribute. + </para> + </listitem></varlistentry> + <varlistentry><term>reserved [optional]</term> + <listitem> + <para> + Reserved for future use. This argument is completely ignored in the current implementation. + </para> + </listitem></varlistentry> </variablelist> </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - xx + Returns a newly instantiated <computeroutput>ooSQLiteConnection</computeroutput> object. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> <listitem> <para> - Additional comments. + Errors can occur when opening the uderlying database, in which case the returned + <computeroutput>ooSQLiteConnection</computeroutput> object can not be used to interact with the database. The + <link linkend="atrInitCodeClsConn">initCode</link> attribute is used to check for errors. The <emphasis + role="italic">initCode</emphasis> attribute will be set to one of ooSQLite <link + linkend="sctResultCode">result</link> code constants. If it is the OK constant there were no errors and the + database can be used. Otherwise, the database can not be use and the <link + linkend="atrLastErrCodeClsConn">lastErrCode</link> and <link linkend="atrLastErrMsgClsConn">lastErrMsg</link> + attributes can be used to determine the exact nature of the failure. </para> + <para> + When an error has occurred, the resources used by the database engine for a connection are released automatically. + Otherwise, every successful open of the database through the instantiation of a + <computeroutput>ooSQLiteConnection</computeroutput> object must be matched by an invocation of the <link + linkend="mthClose">close</link> method to free the resources. Once the database is closed, other methods of the + <computeroutput>ooSQLiteConnection</computeroutput> object can not be used. Note that this does not apply to the + attrbute methods of the object, which are always accessible. As noted, if an error with the database engine happens + during <emphasis role="italic">new</emphasis>, the database engine resources are freed. This is an implicit close of + the database. + </para> + <para> + Do not invoke the methods of the <computeroutput>ooSQLiteConnection</computeroutput> object when an error occurs + during <emphasis role="italic">new</emphasis>. + </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Details</emphasis></term> <listitem> <para> - + The functionality of the <emphasis role="italic">new</emphasis> method is similar to that of the SQLite + <ulink url="http://www.sqlite.org/c3ref/open.html">sqlite3_open_v2</ulink> API. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Example:</emphasis></term> <listitem> <para> - This example ... + This example opens up a connection to the <computeroutput>phoneBook</computeroutput> database, located in the + current directory of the application, and checks for error: <programlisting> <![CDATA[ + db = .ooSQLiteConnection~new('phoneBook.rdbx') + + if db~initCode <> 0 then do + -- handle error in some fashion + ... + end + ]]> </programlisting> </para> @@ -637,7 +701,8 @@ </programlisting> <para> - xx + Over-rides the process-wide default record format set through the OOSQLite <link + linkend="atrRecordFormatClsOOSQLite">class</link> for this database connection. </para> <variablelist> <varlistentry><term><emphasis role="bold">recordFormat get:</emphasis></term> @@ -649,7 +714,9 @@ <varlistentry><term><emphasis role="bold">recordFormat set:</emphasis></term> <listitem> <para> - details about set + This default can still be over-ridden at + <link linkend="clsOOSQLiteStmt">statment</link> or method level. If not over-ridden, all returned result sets + from this database connection will have the format specified by this attribute. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> @@ -874,7 +941,7 @@ <varlistentry><term><emphasis role="bold">Return value:</emphasis></term> <listitem> <para> - An ooSQLite <link linkend="tblOOSQLiteConstants">result</link> code. + An ooSQLite <link linkend="sctResultCode">result</link> code. </para> </listitem></varlistentry> <varlistentry><term><emphasis role="bold">Remarks:</emphasis></term> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |