doc/xml/dio.xml

  <section id="dio">
    <title>DIO - Database Interface Objects</title>
    <refentry id="dio_package">
      <refnamediv>
	<refname>DIO</refname>
	<refpurpose>Database Interface Objects</refpurpose>
      </refnamediv>

   <refsynopsisdiv>
		<cmdsynopsis>
		  <command>::DIO::handle</command>
		  <arg choice="plain"><replaceable>interface</replaceable></arg>
		  <arg choice="opt"><replaceable>objectName</replaceable></arg>
		  <group choice="opt">
		    <arg>-option</arg>
		    <arg><replaceable>option</replaceable></arg>
		    <arg>-option</arg>
		    <arg><replaceable>option</replaceable></arg>
		    <arg>...</arg>
		  </group>
		</cmdsynopsis>
		<cmdsynopsis>
		  <command>::DIO::handle Tdbc</command>
		  <arg choice="plain"><replaceable>interface</replaceable></arg>
		  <arg choice="opt"><replaceable>objectName</replaceable></arg>
		  <group choice="opt">
		    <arg>-option</arg>
		    <arg><replaceable>option</replaceable></arg>
		    <arg>-option</arg>
		    <arg><replaceable>option</replaceable></arg>
		    <arg>...</arg>
		  </group>
		</cmdsynopsis>
   </refsynopsisdiv>
   <refsect1>
	<title>Description</title>
	<para>
	    <command>DIO</command> is designed to be a generic, object-oriented interface to SQL databases.
        Its main goal is to be as generic as possible, but since not all SQL databases support the exact
        same syntaxes, keeping code generic between databases is left to the abilities of the
	    programmer. DIO simply provides a way to keep the Tcl interface generic.
	</para>
	<para>
	    <option>interface</option> - The name of the database interface. 
        Currently supported direct interfaces are <option>Postgresql</option>, <option>Mysql</option>,
        <option>Oracle</option> and <option>Sqlite</option>. Starting with version 1.2 DIO supports also the
        <ulink url="https://tdbc.tcl-lang.org/">TDBC</ulink> DBMS driver series through the
        <option>Tdbc</option> interface. In this form the command requires a further argument for one of the
        TDBC drivers. Avaliable <ulink url="https://tdbc.tcl-lang.org/">TDBC</ulink> drivers are: 
        <option>mysql</option> (supports also MariaDB),
        <option>odbc</option> (provides also support for <option>Oracle</option>), 
        <option>postgresql</option> and <option>sqlite</option>
	</para>
    <para>
      If <option><replaceable>objectName</replaceable></option> is
      specified, DIO creates an object of that name. If there is
      no <option><replaceable>objectName</replaceable></option>
      given, DIO will automatically generate a unique object ID
    </para>
  </refsect1>
  <refsect1>
	<title>Options</title>
	<variablelist>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-host</arg>
		<arg choice="opt"><replaceable>hostname</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		The hostname of the computer to connect to.  If none
		is given, DIO assumes the local host.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-port</arg>
		<arg><replaceable>portNumber</replaceable></arg>
	      </cmdsynopsis>
	      <para>The port number to connect to on <option>hostname</option>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-user</arg>
		<arg><replaceable>username</replaceable></arg>
	      </cmdsynopsis>
	      <para>The username you wish to login to the server as.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-pass</arg>
		<arg><replaceable>password</replaceable></arg>
	      </cmdsynopsis>
	      <para>The password to login to the server with.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-db</arg>
		<arg><replaceable>database</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		The name of the database to connect to.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-table</arg>
		<arg><replaceable>tableName</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		The default table to use when using built-in commands
		for storing and fetching.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-keyfield</arg>
		<arg><replaceable>keyFieldname</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		The default field to use as the primary key when using
		built-in commands for storing and fetching.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-autokey</arg>
		<group>
		  <arg>1</arg>
		  <arg>0</arg>
		</group>
	      </cmdsynopsis>
	      <para>
				If this option is set to 1, DIO will attempt to
				determine an automatic key for
				<option>keyField</option> when storing and fetching.
				In most databases, this requires that the
				<option>sequence</option> also be specified.  In the
				case of MySQL, where sequences do not exist, autokey
				must be used in conjunction with a table which has a
				field specified as AUTO.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain">-sequence</arg>
		<arg><replaceable>sequenceName</replaceable></arg>
	      </cmdsynopsis>
			   <para>
				If DIO is automatically generating keys, it will use
				this sequence as a means to gain a unique number for
				the stored key.</para>
	    </listitem>
	  </varlistentry>

	</variablelist>
    </refsect1>
    <refsect1>
	    <title>DIO Object Commands</title>
	    <variablelist>
          <varlistentry>
            <listitem>
              <cmdsynopsis>
            <arg choice="plain"><replaceable>objectName</replaceable></arg>
            <arg>array</arg>
            <arg><replaceable>request</replaceable></arg>
              </cmdsynopsis>
              <para>
            Execute <option>request</option> as a SQL query and
            create an array from the first record found.  The
            array is set with the fields of the table and the
            values of the record found.</para>
            </listitem>
         </varlistentry>

         <varlistentry>
            <listitem>
              <cmdsynopsis>
                <arg choice="plain"><replaceable>objectName</replaceable></arg>
                <arg>autokey</arg>
                <group choice="opt">
                  <arg>value</arg>
                  <arg>boolean</arg>
                </group>
              </cmdsynopsis>
              <para>
                Return the current autokey value.  If
                <option>value</option> is specified, it sets a new
                value for the autokey option.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <listitem>
              <cmdsynopsis>
            <arg choice="plain"><replaceable>objectName</replaceable></arg>
            <arg>close</arg>
              </cmdsynopsis>
              <para>	      Close the current database connection.  This command is
            automatically called when the DIO object is destroyed.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <listitem>
              <cmdsynopsis>
            <arg choice="plain"><replaceable>objectName</replaceable></arg>
            <arg>count</arg>
              </cmdsynopsis>
              <para>	      Return a count of the number of rows in the
            specified (or current) table.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <listitem>
              <cmdsynopsis>
                <arg choice="plain"><replaceable>objectName</replaceable></arg>
                <arg>db</arg>
                <arg choice="opt"><replaceable>value</replaceable></arg>
              </cmdsynopsis>
              <para>
                Return the current database.  If
                <option>value</option> is specified, it sets a new
                value for the database.  In most cases, the DIO object
                will automatically connect to the new database when
                this option is changed.
              </para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <listitem>
              <cmdsynopsis>
            <arg choice="plain"><replaceable>objectName</replaceable></arg>
            <arg>delete</arg>
            <arg><replaceable>key</replaceable></arg>
            <group choice="opt">
              <arg>-option</arg>
              <arg><replaceable>option</replaceable></arg>
              <arg>...</arg>
            </group>
              </cmdsynopsis>
              <para>
                Delete a record from the database where the primary
                key matches <option>key</option>.
              </para>
            </listitem>
          </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>destroy</arg>
	      </cmdsynopsis>
	      <para>
		Destroy the DIO object.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>errorinfo</arg>
		<arg choice="opt">value</arg>
	      </cmdsynopsis>
	      <para><option>errorinfo</option> contains the value of
		the last error, if any, to occur while executing a
		request.  When a request fails for any reason, this
		variable is filled with the error message from the SQL
		interface package.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>exec</arg>
		<arg><replaceable>request</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Execute <option>request</option> as an SQL query.
		When the exec command is called, the query is
		executed, and a DIO result object is returned.  From
		there, the result object can be used to obtain
		information about the query status and records in a
		generic way.  See <link linkend="resultobj">Result
		  Object Commands</link>
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>fetch</arg>
		<arg><replaceable>key</replaceable></arg>
		<arg><replaceable>arrayName</replaceable></arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Fetch a record from the database where the primary key
		matches <option>key</option> and store the result in
		an array called <option>arrayName</option>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>forall</arg>
		<arg><replaceable>request</replaceable></arg>
		<arg><replaceable>arrayName</replaceable></arg>
		  <arg><replaceable>body</replaceable></arg>
	      </cmdsynopsis>
	      <para>
	       Execute an SQL select <option>request</option> and iteratively 
	       fill the array named <option>arrayName</option>
	       with elements named with the matching field names, and
	       values containing the matching values, repeatedly executing 
	       the specified code <option>body</option>
	       for each row returned.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>host</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current host value.  If
		<option>value</option> is specified, it sets a new
		value for the host.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>insert</arg>
		<arg><replaceable>table</replaceable></arg>
		<arg><replaceable>arrayName</replaceable></arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Insert fields from <option>arrayName</option> into the specified <option>table</option> in the database.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>interface</arg>
	      </cmdsynopsis>
	      <para>
		Return the database interface type, such as 
		<literal>Postgresql</literal> or <literal>Mysql</literal>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>keyfield</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current keyfield.  If
		<option>value</option> is specified, it sets a new
		value for the keyfield.  <option>Value</option> can contain
		multiple key fields as a Tcl list, if the table has multiple
		key fields.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>keys</arg>
		<arg choice="opt"><replaceable>pattern</replaceable></arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Return a list of keys in the database.  If
		<option>pattern</option> is specified, only the keys
		matching will be returned.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>lastkey</arg>
	      </cmdsynopsis>
	      <para>
		Return the last key that was used from
		<option>sequence</option>.  If sequence has not been
		specified, this command returns an empty string.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>list</arg>
		<arg>request</arg>
	      </cmdsynopsis>
	      <para>
		Execute <option>request</option> as a SQL query and
		return a list of the first column of each record
		found.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>makekey</arg>
		<arg><replaceable>arrayName</replaceable></arg>
		<arg choice="opt"><replaceable>keyfield</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Given an array containing key-value pairs and an optional
		list of key fields (we use the object's keyfield if
		none is specified), if we're doing auto keys, create
		and return a new key, otherwise if it's a single key,
		just return its value from the array, else if there are
		multiple keys, return all the keys' values from the
		array as a list.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>nextkey</arg>
	      </cmdsynopsis>
	      <para>Increment <option>sequence</option> and return the
		next key to be used.  If sequence has not been
		specified, this command returns an empty
		string.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>open</arg>
	      </cmdsynopsis>
	      <para>Open the connection to the current database.  This
		command is automatically called from any command which
		accesses the database.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>pass</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current pass value.  If
		<option>value</option> is specified, it sets a new
		value for the password.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>port</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>Return the current port value.  If <option>value</option> is
		specified, it sets a new value for the port.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>quote</arg>
		<arg><replaceable>string</replaceable></arg>
	      </cmdsynopsis>
	      <para>Return the specified <option>string</option> quoted in
	      a way that makes it acceptable as a value in a SQL statement.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>search</arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Search the current table, or the specified table if
		-table tableName is specified, for rows matching
		one or more fields as key-value pairs, and return
		a query result handle.
		See <link linkend="resultobj">Result Object Commands</link>
		</para>
		<para>
		For example,
	<programlisting>set res [DIO search -table people -firstname Bob]</programlisting>
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>sequence</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current sequence value.  If <option>value</option> is
		specified, it sets a new value for the sequence.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>store</arg>
		<arg><replaceable>arrayName</replaceable></arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Store the contents of <option>arrayName</option> in the 
		database, where the keys are the field names and the
		array's values are the corresponding values.  Do an SQL insert 
		if the corresponding row doesn't exist, or an update 
		if it does.
	      </para>
	      <para>
		The table name must have been previously set
		or specified with <arg>-table</arg>, and the key field(s) must
		have been previously set or specified with
		<arg>-keyfield</arg>.
	      </para>
	      <para>
		Please note that the store method has significantly higher 
		overhead than
		the update or insert methods, so if you know you are
		inserting a row rather than updating one, it is advisable
		to use the insert method and, likewise, if you know you
		are updating rather than inserting, to use the
		update method.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>string</arg>
		<arg><replaceable>request</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Execute <option>request</option> as a SQL query and
		return a string containing the first record
		found.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>table</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>Return the current table.  If
		<option>value</option> is specified, it sets a new
		value for the table.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>update</arg>
		<arg><replaceable>arrayName</replaceable></arg>
		<group choice="opt">
		  <arg>-option</arg>
		  <arg><replaceable>option</replaceable></arg>
		  <arg>...</arg>
		</group>
	      </cmdsynopsis>
	      <para>
		Updates the row matching the contents of 
		<option>arrayName</option> in the database.  The matching
		row must already exist.  The table can have already been
		set or can be specified with <arg>-table</arg>, and
		the key field(s) must either have been set or
		specified with <arg>-keyfield</arg>.
	      </para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>objectName</replaceable></arg>
		<arg>user</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current user value.  If
		<option>value</option> is specified, it sets a new
		value for the user.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
      <refsect1 id="resultobj">
	<title>Result Object Commands</title>
	<variablelist>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>autocache</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current autocache value.  If
		<option>value</option> is specified, it sets a new
		value for autocache.
	      </para>
	      <para>
		If autocache is true, the result object will
		automatically cache rows as you use them.  This means
		that the first time you execute a forall command, each
		row is being cached in the result object itself and
		will no longer need to access the SQL result.
		<emphasis>Default is true</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>cache</arg>
	      </cmdsynopsis>
	      <para>
		Cache the results of the current SQL result in the
		result object itself.  This means that even if the
		database connection is closed and all the results of
		the DIO object are lost, this result object will still
		maintain a cached copy of its records.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>errorcode</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current errorcode value.  If <option>value</option>
		is specified, it sets a new value for errorcode.
	      </para>
	      <para>
		<option>errorcode</option> contains the current code from the
		SQL database which specifies the result of the query
		statement which created this object.  This variable
		can be used to determine the success or failure of a
		query.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>errorinfo</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current errorinfo value.  If <option>value</option>
		is specified, it sets a new value for errorinfo.
	      </para>
	      <para>
		If an error occurred during the SQL query, DIO
		attempts to set the value of <option>errorinfo</option> to the
		resulting error message.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>fields</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current fields value.  If
		<option>value</option> is specified, it sets a new
		value for fields.
	      </para>
	      <para>
		<option>fields</option> contains the list of fields
		used in this query.  The fields are in order of the
		fields retrieved for each row.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>forall</arg>
		<arg><replaceable>-type</replaceable></arg>
		<arg><replaceable>varName</replaceable></arg>
		<arg><replaceable>body</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Execute <option>body</option> over each record in the
		result object.
	      </para>
	      <para>Types:</para>
	      <variablelist>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-array</arg>
		    </cmdsynopsis>
		    <para>
		      Create
		      <option><replaceable>varName</replaceable></option>
		      as an array where the indexes are the names of
		      the fields in the table and the values are the
		      values of the current row.
		    </para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-keyvalue</arg>
		    </cmdsynopsis>
		    <para>
		      Set
		      <option><replaceable>varName</replaceable></option>
		      to a list containing key-value pairs of fields
		      and values from the current row. (-field value
		      -field value)
		    </para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-list</arg>
		    </cmdsynopsis>
		    <para>
		      Set
		      <option><replaceable>varName</replaceable></option>
		      to a list that contains the values of the
		      current row.
		    </para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>next</arg>
		<arg><replaceable>-type</replaceable></arg>
		<arg choice="opt"><replaceable>varName</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Retrieve the next record in the result object.
	      </para>
	      <para>Types:</para>
	      <variablelist>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-array</arg>
		    </cmdsynopsis>
		    <para>
		      Create
		      <option><replaceable>varName</replaceable></option>
		      as an array where the indexes are the names of
		      the fields in the table and the values are the
		      values of the current row.
		    </para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-dict</arg>
		    </cmdsynopsis>
		    <para>
		      Set <option><replaceable>varName</replaceable></option>
		      to a list containing ordinary key-value pairs of fields
		      and values from the current row. This form is naturally
		      intepreted as dictionary where each key corresponds
		      to a column. The result representation produced by this
              option is naturally equivalent to the <option>-keyvalue</option>
		   </para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-keyvalue</arg>
		    </cmdsynopsis>
		    <para>
		      Set
		      <option><replaceable>varName</replaceable></option>
		      to a list containing key-value pairs of fields
		      and values from the current row (-field value
		      -field value). This form is handy to build query
		      arguments for the <command>search</command> method 
		      of a DIO object
		    </para>
		  </listitem>
		</varlistentry>
		<varlistentry>
		  <listitem>
		    <cmdsynopsis>
		      <arg choice="plain">-list</arg>
		    </cmdsynopsis>
		    <para>
		      Set
		      <option><replaceable>varName</replaceable></option>
		      to a list that contains the values of the
		      current row.
		    </para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>numrows</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current numrows value.  If <option>value</option> is
		specified, it sets a new value for numrows.
	      </para>
	      <para>
		<option>numrows</option> is the number of rows in this result.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>resultid</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current resultid value.  If <option>value</option> is
		specified, it sets a new value for resultid.
	      </para>
	      <para>
		<option>resultid</option> in most databases is the result
		pointer which was given us by the database.  This
		variable is not generic and should not really be used,
		but it's there if you want it.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <listitem>
	      <cmdsynopsis>
		<arg choice="plain"><replaceable>resultObj</replaceable></arg>
		<arg>rowid</arg>
		<arg choice="opt"><replaceable>value</replaceable></arg>
	      </cmdsynopsis>
	      <para>
		Return the current rowid value.  If <option>value</option> is
		specified, it sets a new value for rowid.
	      </para>
	      <para>
		<option>rowid</option> contains the number of the
		current result record in the result object.  This
		variable should not really be accessed outside of the
		result object, but it's there if you want it.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
    </refentry>
  </section>