tcl.html

TCL的数据库处理支撑库及一些示例

</p><p></p></dd><dt>EXAMPLES</dt><dd>
    Define a cursor pointing to a new empty row:
    <pre>    set cursor [mk::row create]</pre>

    Initialize a temporary view with 100 copies of the string "Hello":
    <pre>    mk::cursor create cursor 
    mk::row insert $cursor 100 [mk::row create text "Hello"]</pre>
<p>
</p><p></p></dd><dt><a name="mk_get"><hr size="1"></a></dt><h2>mk::get</h2><dd><h3>Fetch values</h3>
<p></p></dd><dt>SYNOPSIS</dt><dd><b>mk::get</b> &nbsp;<i>cursor</i> &nbsp;?-size?<br>
<b>mk::get</b> &nbsp;<i>cursor</i> &nbsp;?-size? &nbsp;<i>prop</i> &nbsp;<i>...</i> &nbsp;<br>
<p></p></dd><dt>DESCRIPTION</dt><dd>
    The <b>mk::get</b> command fetches values from the row specified by <i>cursor</i>.
<p>
    Without argument, <i>get</i> returns a list of <i>'prop1 value1 prop2 value2 ...'</i>.
    This format is most convenient for setting an array variable, as the following
    example illustrates:
    </p><pre>    array set v [mk::get db.phonebook!0]
    parray v</pre>
    Note that the <i>cursor</i> argument can be the value of a cursor variable,
    or it can be synthesized on the spot, as in the above example.
<p>
	If the <b>-size</b> option is specified, the size of property values is
	returned instead of their contents.  This is normally in bytes, but for 
	integers it can be a negative value indicating the number of bits used
	to store ints (-1, -2, or -4).  This is an efficient way to determine the
	sizes of property values without fetching them.
</p><p>
    If arguments are specified in the <i>get</i> command, they are interpreted as
    property names and a list will be returned
    containing the values of these properties in the specified order.
</p><p>
    If <i>cursor</i> does not point to a valid row, default values are returned
    instead (no properties, and empty strings or numeric zero's, according to
    the property types).
</p><p>
</p><p></p></dd><dt>EXAMPLES</dt><dd>
    Set up an array containing all the fields in the third row:
    <pre>    array set fields [mk::get db.phonebook!2]</pre>

    Created a line with some formatted fields:

    <pre>    puts [eval [list format {%-20s %d}] [mk::get db.phonebook!2 name date]]</pre>
<p>
</p><p></p></dd><dt><a name="mk_set"><hr size="1"></a></dt><h2>mk::set</h2><dd><h3>Store values</h3>
<p></p></dd><dt>SYNOPSIS</dt><dd><b>mk::set</b> &nbsp;<i>cursor</i> &nbsp;<i>?prop</i> &nbsp;<i>value</i> &nbsp;<i>...?</i> &nbsp;<br>
<p></p></dd><dt>DESCRIPTION</dt><dd>
    The <b>mk::set</b> command stores values into the row specified by <i>cursor</i>.
<p>
    If a property is specified which does not exist, it will be appended as a new
    definition for the containing view.  As an important side effect, all other
    rows in this view will now also have such a property, with an appropriate
    default value for the property.  Note that when new
    properties are defined in this way, they will be created as string properties
    unless qualified by a type suffix (see <i>'mk::view layout'</i> for details on
    property types and their default values).
</p><p>
    Using <i>mk::set</i> command without specifying properties
    returns the current value and is identical to <i>mk::get</i>.
</p><p>
    If <i>cursor</i> points to a non-existent row past the end of the view,
    an appropriate number of empty rows will be inserted first.
</p><p>
</p><p></p></dd><dt><a name="mk_loop"><hr size="1"></a></dt><h2>mk::loop</h2><dd><h3>Iterate over the rows of a view</h3>
<p></p></dd><dt>SYNOPSIS</dt><dd><b>mk::loop</b> &nbsp;<i>cursorName</i> &nbsp;<i>{body}</i> &nbsp;<br>
<b>mk::loop</b> &nbsp;<i>cursorName</i> &nbsp;<i>path</i> &nbsp;<i>{body}</i> &nbsp;<br>
<b>mk::loop</b> &nbsp;<i>cursorName</i> &nbsp;<i>path</i> &nbsp;<i>first</i> &nbsp;<i>?limit?</i> &nbsp;<i>?step?</i> &nbsp;<i>{body}</i> &nbsp;<br>
<p></p></dd><dt>DESCRIPTION</dt><dd>
    The <b>mk::loop</b> command offers a convenient way to iterate over the
    rows of a view.  Iteration can be restricted to a certain range, and
    can optionally use a forward or backward step.  This is a convenience function
    which is more efficient than performing explicit iteration over an
    index and positioning a cursor.
<p>
    When called with just a <i>path</i> argument, the loop will iterate over all the rows
    in the corresponding view.
    The <i>cursorName</i> loop variable will be set (or reset) on each iteration,
    and is created if it did not yet exist.
</p><p>
    When <i>path</i> is not specified, 
    the <i>cursorName</i> variable must exist and be a valid
    cursor, although its current position will be ignored.
    The command <i>'mk::loop X {...}'</i> is identical to <i>'mk::loop X $X {...}'</i>.
</p><p>
    The <i>first</i> argument specifies
    the first index position to use (default 0),
    the <i>limit</i> argument specifies the last argument (default 'end'),
    and the <i>step</i> argument specifies the increment (default 1).
    If <i>step</i> is negative and <i>limit</i> exceeds <i>first</i>, then the loop body will 
    never be executed.  A zero <i>step</i> value can lead to infinite
    looping unless the <i>break</i> command is called inside the loop.
</p><p>
    The <i>first</i>, <i>limit</i>, and <i>step</i> arguments may be arbitrary integer
    expressions and are evaluated exactly once when the loop is entered.
</p><p>Note that you cannot easily use a loop to insert or delete rows,
since changes to views do not adjust cursors pointing into that view.
Instead, you can use tricks like moving backwards (for deletions), or
splitting the work into two separate passes. </p><p></p></dd><dt><a name="mk_elect"><hr size="1"></a></dt><h2>mk::select</h2><dd><h3>Selection and sorting</h3>
<p></p></dd><dt>SYNOPSIS</dt><dd><b>mk::select</b> &nbsp;<i>path</i> &nbsp;<i>?options</i> &nbsp;<i>...?</i> &nbsp;<br>
<p></p></dd><dt>DESCRIPTION</dt><dd>
    The <b>mk::select</b> command combines a flexible selection operation with a way to sort
    the resulting set of rows.  The result is a list of row index numbers (possibly
    empty), which can be used to reposition a cursor and to address rows directly.
<p>
    A selection is specified using any combination of these criteria:
    </p><ul><dl>
        <dt> <i>prop</i> <i>value</i> </dt><dd>
            Numeric or case-insensitive match
        </dd><dt> <b>-min</b> <i>prop</i> <i>value</i> </dt><dd>
            Property must be greater or equal to value (case is ignored)
        </dd><dt> <b>-max</b> <i>prop</i> <i>value</i> </dt><dd>
            Property must be less or equal to value (case is ignored)
        </dd><dt> <b>-exact</b> <i>prop</i> <i>value</i> </dt><dd>
            Exact case-sensitive string match
        </dd><dt> <b>-glob</b> <i>prop</i> <i>pattern</i> </dt><dd>
            Match "glob-style" expression wildcard
        </dd><dt> <b>-globnc</b> <i>prop</i> <i>pattern</i> </dt><dd>
            Match "glob-style" expression, ignoring case
        </dd><dt> <b>-regexp</b> <i>prop</i> <i>pattern</i> </dt><dd>
            Match specified regular expression
        </dd><dt> <b>-keyword</b> <i>prop</i> <i>word</i> </dt><dd>
            Match word as free text or partial prefix
    </dd></dl></ul>
    If multiple criteria are specified, then
    selection succeeds only if all criteria are satisfied.
    If <i>prop</i> is a list, selection succeeds if <i>any</i> of the
    given properties satisfies the corresponding match.
<p>
    Optional selection constraints:
    </p><ul><dl>
        <dt> <b>-first</b> <i>pos</i> </dt><dd>
            Selection starts at specified row index
        </dd><dt> <b>-count</b> <i>num</i> </dt><dd>
            Return no more than this many results
    </dd></dl></ul>
    Note: not yet very useful with sorting, which is
    done after these constraints have been applied.
<p>
    To sort the set of rows (with or without preliminary selection), use:
    </p><ul><dl>
        <dt> <b>-sort</b> <i>prop</i> <br>
             <b>-sort</b> {<i>prop</i> ...} </dt><dd>
            Sort on one or more properties, ascending
        </dd><dt> <b>-rsort</b> <i>prop</i> <br>
             <b>-rsort</b> {<i>prop</i> ...} </dt><dd>
            Sort on one or more properties, descending
    </dd></dl></ul>
    Multiple sort options are combined in the order given.
<p>
</p><p></p></dd><dt>EXAMPLES</dt><dd>
    Select a range of entries:
    <pre>    foreach i [mk::select db.phonebook -min date 19980101 -max date 19980131] {
        puts "Dated Jan 1998: [mk::get db.phonebook!$i name]"
    }</pre>

    Search for a unique match (<i>'-count 2'</i>
    speeds up selection when many entries match):
    <pre>    set v [mk::select db.phonebook -count 2 -glob name "John*"]
    switch [llength $v] {
        0       {puts "not found"}
        1       {puts "found: [mk::get db.phonebook![lindex $v 0] name]"}
        2       {puts "there is more than one entry matching 'John*'"}
    }</pre>

    Sort by descending date and by ascending name:
    <pre>    foreach i [mk::select db.phonebook -rsort date -sort name] {
        puts "Change log: [mk::get db.phonebook!$i date name]"
    }</pre>
<p>
</p><p></p></dd><dt><a name="mk_channel"><hr size="1"></a></dt><h2>mk::channel</h2><dd><h3>Channel interface</h3>
<p></p></dd><dt>SYNOPSIS</dt><dd><b>mk::channel</b> &nbsp;<i>path</i> &nbsp;<i>prop</i> &nbsp;<i>?mode?</i> &nbsp;<br>
<p></p></dd><dt>DESCRIPTION</dt><dd>
    The <b>mk::channel</b> command provides a channel interface to binary
    fields.  It needs the <i>path</i> of a row and the name of a binary
    <i>prop</i>, and returns a channel
    descriptor which can be used to read or write from.
<p>
    Channels are opened in one of three modes:
    </p><blockquote>
             <b>read</b> - <i>open for reading existing contents (default)</i> <br>
             <b>write</b> - <i>clear contents and start saving data</i><br>
             <b>append</b> - <i>keep contents, set seek pointer to end</i>
    </blockquote>
<p>
    Note: do not insert or delete rows in a view within which there are
    open channels, because subsequent reads and writes may end up going
    to the wrong memo property.
</p><p>
</p></dd><dt>EXAMPLES</dt><dd>
    Write a few values (with line separators):
    <pre>    mk::view layout db.v {b:B}
    mk::view size db.v 1

    set fd [mk::channel db.v!0 b w]
    puts $fd one
    puts $fd two
    puts $fd three
    close $fd</pre>
    
    Read values back, line by line:
    <pre>    set fd [mk::channel db.v!0 b]
    while {[gets $fd text] &gt;= 0} {
        puts $text
    }
    close $fd</pre>
<p>
</p></dd></dl>
<!--END-->
<p>
</p><hr size="1">
&#169; 2005 Jean-Claude Wippler &lt;<a href="mailto:[e-mail]">[e-mail]</a>&gt;

</body></html>