metakit for tcl.mht

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

  <I>filename</I> is omitted, a temporary in-memory dataset is created =
(which=20
  cannot use commit, but which you could save to an I/O channel). When a =

  datafile is closed, all pending changes will be written to file, =
unless the=20
  <B>-nocommit</B> option is specified. In that case, only an explicit =
commit=20
  will save changes. To open a file only for reading, use the =
<B>-readonly</B>=20
  option. Datafiles can be opened read-only by any number of readers, or =
by a=20
  single writer (no other combinations are allowed). There is an =
additional=20
  mode, specified by the <B>-extend</B> option: in this case changes are =
always=20
  written at the end of the datafile. This allows modifications by one =
writer=20
  without affecting readers. Readers can adjust to new changes made that =
way by=20
  doing a "rollback" (see below). The term is slightly confusing in this =
case,=20
  since it really is a "roll-forward" ... The <B>-shared</B> option =
causes an=20
  open datafile to be visible in every Tcl interpreter, with thread =
locking as=20
  needed. The datafile is still tied to the current interpreter and will =
be=20
  closed when that interpreter is terminated.=20
  <P>The '<B>mk::file views</B>' command returns a list with the views =
currently=20
  defined in the open datafile associated with <I>tag</I>. You can use =
the=20
  <I>'mk::view layout'</I> command to determine the current structure of =
each=20
  view.=20
  <P>The '<B>mk::file close</B>' command closes the datafile and =
releases all=20
  associated resources. If not opened with <I>-readonly</I> or =
<I>-nocommit</I>,=20
  all pending changes will be saved to file before closing it. A =
<I>tag</I>=20
  loses its special meaning after the corresponding datafile has been =
closed.=20
  <P>The '<B>mk::file commit</B>' command flushes all pending changes to =
disk.=20
  It should not be used on a file opened with the <I>-readonly</I> =
option. The=20
  optional <I>-full</I> argument is only useful when a =
<I>commit-aside</I> is=20
  active (see below). In that case, changes are merged back into the =
main=20
  datafile instead of being saved separately. The aside dataset is =
cleared.=20
  <P>The '<B>mk::file rollback</B>' command cancels all pending changes =
and=20
  reverts the situation to match what was last stored on file. When =
commit-aside=20
  is active, a full rollback cause the state to be rollback to what it =
was=20
  without the aside changes. The aside dataset will be ignored from now =
on.=20
  <P>The '<B>mk::file load</B>' command replaces all views with data =
read from=20
  any Tcl <I>channel</I>. This data must have been generated using =
'<B>mk::file=20
  save</B>'. Changes are made permanent when <I>commit</I> is called =
(explicitly=20
  or implicitly, when a datafile is closed), or they can be reverted by =
calling=20
  <I>rollback</I>.=20
  <P>The '<B>mk::file aside</B>' command starts a special "commit-aside" =
mode,=20
  whereby changes are saved to a second database file. This can be much =
faster=20
  that standard commits, because only changes are saved. In commit- =
aside mode,=20
  the main datafile will not be modified it all, in fact it can be =
opened in=20
  read-only mode.=20
  <P>The '<B>mk::file autocommit</B>' command sets up a database file to =

  automatically issue a commit when the file is closed later. This is =
useful if=20
  the file was initially opened in <I>-nocommit</I> mode, but you now =
want to=20
  change this setting (there is no way to return to <I>-nocommit</I>, =
although a=20
  rollback has a similar effect).=20
  <P>
  <P></P>
  <DT>EXAMPLES
  <DD>Open a datafile (create it if necessary), for read-write access: =
<PRE>    mk::file open db test.dat</PRE>Display the structure of every =
view in=20
  the datafile: <PRE>    foreach v [mk::file views db] {
        puts [mk::view layout db.$v]
    }</PRE>Send all data across a TCP/IP socket connection: <PRE>    set =
chan [socket 127.0.0.1 12345]
    mk::file save db $chan
    close $chan</PRE>The trick to open a datafile stored inside another =
MK=20
  file (e.g. in VFS) is to load/save data via an in-memory database - =
replace=20
  this: <PRE>    mk::file open db test.dat -readonly</PRE>by this: <PRE> =
   mk::file open db
    set fd [open test.dat]
    mk::file load db $fd
    close $fd</PRE>
  <P>
  <P></P>
  <DT><A name=3Dmk_view>
  <HR SIZE=3D1>
  </A>
  <H2>mk::view</H2>
  <DD>
  <H3>View structure and size operations</H3>
  <P></P>
  <DT>SYNOPSIS
  <DD><B>mk::view</B> &nbsp;<B>layout</B> &nbsp;<I>tag.view</I>=20
  &nbsp;<BR><B>mk::view</B> &nbsp;<B>layout</B> &nbsp;<I>tag.view</I>=20
  &nbsp;<I>{structure}</I> &nbsp;<BR><B>mk::view</B> &nbsp;<B>delete</B> =

  &nbsp;<I>tag.view</I> &nbsp;<BR><B>mk::view</B> &nbsp;<B>size</B>=20
  &nbsp;<I>path</I> &nbsp;<BR><B>mk::view</B> &nbsp;<B>size</B>=20
  &nbsp;<I>path</I> &nbsp;<I>size</I> &nbsp;<BR><B>mk::view</B>=20
  &nbsp;<B>info</B> &nbsp;<I>path</I> &nbsp;<BR>
  <P></P>
  <DT>DESCRIPTION
  <DD>The <I>mk::view</I> command is used to query or alter the =
structure of a=20
  <I>view</I> in a datafile (<I>layout</I>, <I>delete</I>), as well as =
the=20
  number of rows it contains (<I>size</I>). The last command =
(<I>info</I>)=20
  returns the list of properties currently defined for a view.=20
  <P>The '<B>mk::view layout</B>' command returns a description of the =
current=20
  datastructure of <I>tag.view</I>. If a structure is specified, the =
current=20
  data is restructured to match that, by adding new properties with a =
default=20
  value, deleting obsolete ones, and reordering them.=20
  <P>Structure definitions consist of a list of properties. Subviews are =

  specified as a sublist of two entries: the name and the list of =
properties in=20
  that subview. Note that subviews add <I>two</I> levels of nesting (see =

  <I>phones</I> in the phonebook example below). The type of a property =
is=20
  specified by appending a suffix to the property name (the default type =
is=20
  string):=20
  <P>
  <UL>
    <DL compact>
      <DT><B>:S</B>=20
      <DD>A <B>string</B> property for storing strings of any size, but =
no null=20
      bytes.=20
      <DT><B>:I</B>=20
      <DD>An <B>integer</B> property for efficiently storing values as =
integers=20
      (1..32 bits).=20
      <DT><B>:L</B>=20
      <DD>An <B>long</B> property for storing values as 64-bit integers. =

      <DT><B>:F</B>=20
      <DD>A <B>float</B> property for storing single-precision floating =
point=20
      values (32 bits).=20
      <DT><B>:D</B>=20
      <DD>A <B>double</B> property for storing double-precision floating =
point=20
      values (64 bits).=20
      <DT><B>:B</B>=20
      <DD>A <B>binary</B> property for untyped binary data (including =
null=20
      bytes).=20
      <DT><B>:M</B>=20
      <DD>Obsolete (now treated as <B>:B</B>). </DD></DL></UL>
  <P>Properties which are not listed int the layout will only remain set =
while=20
  the datafile is open, but not be stored. To make properties persist, =
you must=20
  list them in the layout definition, and do so <I>before</I> setting =
them.=20
  <P>The '<B>mk::view delete</B>' command completely removes a view and =
all the=20
  data it contains from a datafile.=20
  <P>The '<B>mk::view size</B>' command returns the number of rows =
contained in=20
  the view identified as <I>tag.view</I>. If an argument is specified, =
the size=20
  of the view is adjusted accordingly, dropping the highest rows if the =
size is=20
  decreased or adding new empty ones if the size is increased. The =
command=20
  <I>'mk::view size 0'</I> deletes all rows from a view, but keeps the =
view in=20
  the datafile so rows can be added again later (unlike <I>'mk::view=20
  delete'</I>.=20
  <P>The '<B>mk::view info</B>' returns the list of properties which are =

  currently defined for <I>path</I>.<BR>
  <P>Note that the <I>layout</I> and <I>delete</I> sub-commands operate =
only on=20
  top-level views (of the form <I>tag.view</I>), whereas <I>size</I> and =

  <I>info</I> take a <I>path</I> as arguments, which is either a =
top-level view=20
  or a nested subview (of the form=20
  'tag.view!index.subview!subindex...<I>etc</I>...subview').=20
  <P>
  <P></P>
  <DT>EXAMPLES
  <DD>Define a phonebook view which can store more than one phone number =
for=20
  each person: <PRE>    mk::view layout db.book {name address {phones =
{category phone}}}</PRE>Add=20
  a new phonebook entry: <PRE>    mk::row append db.book name "Steve" =
address "Down-under"</PRE>Add two=20
  phone numbers to phone book entry zero, i.e. "Steve": <PRE>    mk::row =
append db.book!0.phones category "home" phone "1234567"
    mk::row append db.book!0.phones category "mobile" phone =
"2345678"</PRE>Restructure=20
  the view in the datafile, adding an integer date field: <PRE>    =
mk::view layout db.book {name address {phones {category phone}} =
date:I}</PRE>Delete=20
  all phonebook entries as well as its definition from the datafile: =
<PRE>    mk::view delete db.book</PRE>
  <P>
  <P></P>
  <DT><A name=3Dmk_cursor>
  <HR SIZE=3D1>
  </A>
  <H2>mk::cursor</H2>
  <DD>
  <H3>Cursor variables for positioning</H3>
  <P></P>
  <DT>SYNOPSIS
  <DD><B>mk::cursor</B> &nbsp;<B>create</B> &nbsp;<I>cursorName</I>=20
  &nbsp;<I>?path?</I> &nbsp;<I>?index?</I> &nbsp;<BR><B>mk::cursor</B>=20
  &nbsp;<B>position</B> &nbsp;<I>cursorName</I> =
&nbsp;<BR><B>mk::cursor</B>=20
  &nbsp;<B>position</B> &nbsp;<I>cursorName</I> &nbsp;<I>0</I>=20
  &nbsp;<BR><B>mk::cursor</B> &nbsp;<B>position</B> =
&nbsp;<I>cursorName</I>=20
  &nbsp;<I>end</I> &nbsp;<BR><B>mk::cursor</B> &nbsp;<B>position</B>=20
  &nbsp;<I>cursorName</I> &nbsp;<I>index</I> &nbsp;<BR><B>mk::cursor</B> =

  &nbsp;<B>incr</B> &nbsp;<I>cursorName</I> &nbsp;<I>?step?</I> =
&nbsp;<BR>
  <P></P>
  <DT>DESCRIPTION
  <DD>The <I>mk::cursor</I> command is used to manipulate <I>'cursor=20
  variables'</I>, which offer an efficient means of iterating and =
repositioning=20
  a <I>'reference to a row in a view'</I>. Though cursors are equivalent =
to=20
  strings of the form <I>somepath!N</I>, it is much more efficient to =
keep a=20
  cursor around in a variable and to adjust it (using the =
<I>position</I>=20
  subcommand), than evaluating a 'somepath!$index' expression every time =
a=20
  cursor is expected.=20
  <P>The '<B>mk::cursor create</B>' command defines (or redefines) a =
cursor=20
  variable. The <I>index</I> argument defaults to zero. This is a =
convenience=20
  function, since <I>'mk::cursor create X somePath N'</I> is equivalent =
to=20
  <I>'set X somePath!N'</I>.=20
  <P>When both <I>path</I> and <I>index</I> arguments are omitted from =
the=20
  <I>'mk::cursor create'</I> command, a cursor pointing to an empty =
temporary=20
  view is created, which can be used as buffer for data not stored on =
file.=20
  <P>The '<B>mk::cursor position</B>' command returns the current =
position of a=20
  cursor, i.e. the 0-based index of the row it is pointing to. If an =
extra=20
  argument is specified, the cursor position will be adjusted =
accordingly. The=20
  '<I>end</I>' pseudo-position is the index of the last row (or -1 if =
the view=20
  is currently empty). Note that if '<I>X</I>' is a cursor equivalent to =

  <I>somePath!N</I>, then <I>'mk::cursor position X M'</I> is equivalent =
to the=20
  far less efficient <I>'set X somePath!M'</I>.=20
  <P>The '<B>mk::cursor incr</B>' command adjusts the current position =
of a=20
  cursor with a specified relative <I>step</I>, which can be positive as =
well as=20
  negative. If <I>step</I> is zero, then this command does nothing. The =
command=20
  <I>'mk::cursor incr X N'</I> is equivalent to <I>'mk::cursor position =
X [expr=20
  {[mk::cursor position X] + N}]'</I>.=20
  <P>
  <P></P>
  <DT><A name=3Dmk_row>
  <HR SIZE=3D1>
  </A>
  <H2>mk::row</H2>
  <DD>
  <H3>Create, insert, and delete rows</H3>
  <P></P>
  <DT>SYNOPSIS
  <DD><B>mk::row</B> &nbsp;<B>create</B> &nbsp;<I>?prop</I> =
&nbsp;<I>value</I>=20
  &nbsp;<I>...?</I> &nbsp;<BR><B>mk::row</B> &nbsp;<B>append</B>=20
  &nbsp;<I>path</I> &nbsp;<I>?prop</I> &nbsp;<I>value</I> =
&nbsp;<I>...?</I>=20
  &nbsp;<BR><B>mk::row</B> &nbsp;<B>insert</B> &nbsp;<I>cursor</I>=20
  &nbsp;<I>count</I> &nbsp;<I>?cursor2?</I> &nbsp;<BR><B>mk::row</B>=20
  &nbsp;<B>delete</B> &nbsp;<I>cursor</I> &nbsp;<I>?count?</I>=20
  &nbsp;<BR><B>mk::row</B> &nbsp;<B>replace</B> &nbsp;<I>cursor</I>=20
  &nbsp;<I>?cursor2?</I> &nbsp;<BR>
  <P></P>
  <DT>DESCRIPTION
  <DD>The <I>mk::row</I> command deals with one or more rows of =
information.=20
  There is a command to allocate a temporary row which is not part of =
any=20
  datafile (<I>create</I>), and the usual set of container operations:=20
  appending, inserting, deleting, and replacing rows.=20
  <P>The '<B>mk::row create</B>' command creates an empty temporary row, =
which=20
  is not stored in any datafile. Each temporary rows starts out without =
any=20
  properties. Setting a property in a row will implicitly add that =
property if=20
  necessary. The return value is a unique <I>cursor</I>, pointing to =
this=20
  temporary row. The row (and all data stored in it) will cease to exist =
when no=20
  cursor references to it remain.=20
  <P>The '<B>mk::row append</B>' command extends the view with a new =
row,=20
  optionally setting some properties in it to the specified values.=20
  <P>The '<B>mk::row insert</B>' command is similar to the <I>append</I> =

  sub-command, inserting the new row in a specified position instead of =
at the=20
  end. The <B>count</B> argument can be used to efficiently insert =
multiple=20
  copies of a row.=20
  <P>The '<B>mk::row delete</B>' command deletes one or more rows from a =
view,=20
  starting at the row pointed to by <I>cursor</I>.=20
  <P>The '<B>mk::row replace</B>' command replaces one row with a copy =
of=20
  another one, or clears its contents if <I>cursor2</I> is not =
specified.=20
  <P>