<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>DIO</title><link rel="stylesheet" type="text/css" href="rivet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Apache Rivet 3.0"><link rel="up" href="dio.html" title="DIO - Database Interface Objects"><link rel="prev" href="dio.html" title="DIO - Database Interface Objects"><link rel="next" href="diodisplay.html" title="DIODisplay - Database Interface Objects Display Class"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DIO</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="dio.html"><img src="images/prev.png" alt="Prev"></a> </td><th width="60%" align="center">DIO - Database Interface Objects</th><td width="20%" align="right"> <a accesskey="n" href="diodisplay.html"><img src="images/next.png" alt="Next"></a></td></tr></table></div><div class="refentry"><a name="dio_package"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>DIO — Database Interface Objects</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "><span style="font-weight:bold ; font-family:monospace">::DIO::handle</span> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>interface</code></em></span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div></div><div class="refsect1"><a name="idm2058"></a><h2>Description</h2><p style="width:90%"> | |
<span style="font-family:monospace"><span class="command"><strong>DIO</strong></span></span> 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. | |
</p><p style="width:90%"> | |
interface - The name of the database | |
interface. Currently supported interfaces are | |
Postgresql and Mysql. | |
</p><p style="width:90%"> | |
If <em class="replaceable"><code>objectName</code></em> is | |
specified, DIO creates an object of that name. If there is | |
no <em class="replaceable"><code>objectName</code></em> | |
given, DIO will automatically generate a unique object ID | |
</p></div><div class="refsect1"><a name="idm2071"></a><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-host</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>hostname</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The hostname of the computer to connect to. If none | |
is given, DIO assumes the local host. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-port</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>portNumber</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The port number to connect to on hostname.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-user</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>username</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The username you wish to login to the server as.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-pass</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>password</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">The password to login to the server with.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-db</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>database</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The name of the database to connect to. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-table</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>tableName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The default table to use when using built-in commands | |
for storing and fetching.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyfield</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>keyFieldname</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The default field to use as the primary key when using | |
built-in commands for storing and fetching.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-autokey</span> (<span style="font-family:monospace; font-weight: bold;">1</span> | <span style="font-family:monospace; font-weight: bold;">0</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
If this option is set to 1, DIO will attempt to | |
determine an automatic key for | |
keyField when storing and fetching. | |
In most databases, this requires that the | |
sequence 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-sequence</span> ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>sequenceName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
If DIO is automatically generating keys, it will use | |
this sequence as a means to gain a unique number for | |
the stored key.</div></div></dd></dl></div></div><div class="refsect1"><a name="idm2141"></a><h2>DIO Object Commands</h2><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">array</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute request 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">autokey</span>? (<span style="font-family:monospace; font-weight: bold;">value</span> | <span style="font-family:monospace; font-weight: bold;">boolean</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current autokey value. If | |
value is specified, it sets a new | |
value for the autokey option.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">close</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> Close the current database connection. This command is | |
automatically called when the DIO object is destroyed.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">count</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> Return a count of the number of rows in the | |
specified (or current) table.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">db</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current database. If | |
value 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">delete</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Delete a record from the database where the primary | |
key matches key.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">destroy</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Destroy the DIO object. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorinfo</span>? ?<span style="font-family:monospace; font-weight: bold;">value</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">errorinfo 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.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">exec</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute request 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 <a class="link" href="dio_package.html#resultobj" title="Result Object Commands">Result | |
Object Commands</a> | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">fetch</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>key</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Fetch a record from the database where the primary key | |
matches key and store the result in | |
an array called arrayName. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">forall</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>body</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute an SQL select request and iteratively | |
fill the array named arrayName | |
with elements named with the matching field names, and | |
values containing the matching values, repeatedly executing | |
the specified code body | |
for each row returned. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">host</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current host value. If | |
value is specified, it sets a new | |
value for the host. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">insert</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>table</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Insert fields from arrayName into the specified table in the database. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">interface</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the database interface type, such as | |
<code class="literal">Postgresql</code> or <code class="literal">Mysql</code>. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">keyfield</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current keyfield. If | |
value is specified, it sets a new | |
value for the keyfield. Value can contain | |
multiple key fields as a Tcl list, if the table has multiple | |
key fields. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">keys</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>pattern</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return a list of keys in the database. If | |
pattern is specified, only the keys | |
matching will be returned. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">lastkey</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the last key that was used from | |
sequence. If sequence has not been | |
specified, this command returns an empty string. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">list</span>? ?<span style="font-family:monospace; font-weight: bold;">request</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute request as a SQL query and | |
return a list of the first column of each record | |
found. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">makekey</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>keyfield</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">nextkey</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Increment sequence and return the | |
next key to be used. If sequence has not been | |
specified, this command returns an empty | |
string.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">open</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Open the connection to the current database. This | |
command is automatically called from any command which | |
accesses the database.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">pass</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current pass value. If | |
value is specified, it sets a new | |
value for the password. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">port</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the current port value. If value is | |
specified, it sets a new value for the port.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">quote</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>string</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the specified string quoted in | |
a way that makes it acceptable as a value in a SQL statement. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">search</span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
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 <a class="link" href="dio_package.html#resultobj" title="Result Object Commands">Result Object Commands</a> | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
For example, | |
<pre class="programlisting">set res [DIO search -table people -firstname Bob]</pre> | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">sequence</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current sequence value. If value is | |
specified, it sets a new value for the sequence. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">store</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Store the contents of arrayName 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. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
The table name must have been previously set | |
or specified with ?<span style="font-family:monospace; font-weight: bold;">-table</span>?, and the key field(s) must | |
have been previously set or specified with | |
?<span style="font-family:monospace; font-weight: bold;">-keyfield</span>?. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">string</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>request</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute request as a SQL query and | |
return a string containing the first record | |
found.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">table</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex">Return the current table. If | |
value is specified, it sets a new | |
value for the table.</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">update</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>arrayName</code></em></span>? (<span style="font-family:monospace; font-weight: bold;">-option</span> | <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>option</code></em></span> | <span style="font-family:monospace; font-weight: bold;">...</span>)</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Updates the row matching the contents of | |
arrayName in the database. The matching | |
row must already exist. The table can have already been | |
set or can be specified with ?<span style="font-family:monospace; font-weight: bold;">-table</span>?, and | |
the key field(s) must either have been set or | |
specified with ?<span style="font-family:monospace; font-weight: bold;">-keyfield</span>?. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>objectName</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">user</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current user value. If | |
value is specified, it sets a new | |
value for the user. | |
</div></div></dd></dl></div></div><div class="refsect1"><a name="resultobj"></a><h2>Result Object Commands</h2><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">autocache</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current autocache value. If | |
value is specified, it sets a new | |
value for autocache. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
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. | |
<span class="emphasis"><em>Default is true</em></span>. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">cache</span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorcode</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current errorcode value. If value | |
is specified, it sets a new value for errorcode. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
errorcode 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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">errorinfo</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current errorinfo value. If value | |
is specified, it sets a new value for errorinfo. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
If an error occurred during the SQL query, DIO | |
attempts to set the value of errorinfo to the | |
resulting error message. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">fields</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current fields value. If | |
value is specified, it sets a new | |
value for fields. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
fields contains the list of fields | |
used in this query. The fields are in order of the | |
fields retrieved for each row. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">forall</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>-type</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>body</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Execute body over each record in the | |
result object. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex">Types:</div><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-array</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Create | |
<em class="replaceable"><code>varName</code></em> | |
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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyvalue</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Set | |
<em class="replaceable"><code>varName</code></em> | |
to a list containing key-value pairs of fields | |
and values from the current row. (-field value | |
-field value) | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-list</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Set | |
<em class="replaceable"><code>varName</code></em> | |
to a list that contains the values of the | |
current row. | |
</div></div></dd></dl></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">next</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>-type</code></em></span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>varName</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Retrieve the next record in the result object. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex">Types:</div><div class="variablelist"><dl class="variablelist"><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-array</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Create | |
<em class="replaceable"><code>varName</code></em> | |
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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-keyvalue</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Set | |
<em class="replaceable"><code>varName</code></em> | |
to a list containing key-value pairs of fields | |
and values from the current row. (-field value | |
-field value) | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;">-list</span> </div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Set | |
<em class="replaceable"><code>varName</code></em> | |
to a list that contains the values of the | |
current row. | |
</div></div></dd></dl></div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">numrows</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current numrows value. If value is | |
specified, it sets a new value for numrows. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
numrows is the number of rows in this result. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">resultid</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current resultid value. If value is | |
specified, it sets a new value for resultid. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
resultid 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. | |
</div></div></dd><dt></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div class="cmdsynopsis" style="width:80%"><div style="border: 1px solid #282; margin:1ex ; padding:.4ex; padding-left: 0.8ex; word-spacing:1ex "> <span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>resultObj</code></em></span> ?<span style="font-family:monospace; font-weight: bold;">rowid</span>? ?<span style="font-family:monospace; font-weight: bold;"><em class="replaceable"><code>value</code></em></span>?</div></div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
Return the current rowid value. If value is | |
specified, it sets a new value for rowid. | |
</div><div style="margin-bottom:1.5ex ; padding .5ex"> | |
rowid 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. | |
</div></div></dd></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dio.html"><img src="images/prev.png" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="dio.html"><img src="images/up.png" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="diodisplay.html"><img src="images/next.png" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">DIO - Database Interface Objects </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a></td><td width="40%" align="right" valign="top"> DIODisplay - Database Interface Objects Display Class</td></tr></table></div></body></html> |