tclstorage(n) 1.0.0 "tclstorage"

NAME

tclstorage - Structured storage access tcl extension

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    COMMANDS
    ENSEMBLE COMMANDS
    AUTHORS
    KEYWORDS
    COPYRIGHT

SYNOPSIS

package require Tcl 8.2
package require Storage ?1.0.0?

storage open filename ?mode?

$stg opendir name ?mode?

$stg open name ?mode?

$stg close

$stg stat name varname

$stg commit

$stg rename oldname newname

$stg remove name

$stg names

This package is an extension that adds the ability to access and manipulate Microsoft's "Structured Storage" files to Tcl. Structured storages are used extensively in Windows to provide persistence for OLE or COM components and as a composite file for various applications. The format presents a filesystem-like hierarchy of storages and streams that maps well into Tcl's virtual filesystem model.

Notable users of structured storages are Microsoft Word and Excel.

COMMANDS

storage open filename ?mode?: Creates or opens a structured storage file. This will create a unique command in the Tcl interpreter that can be used to access the contents of the storage. The file will remain open with exclusive access until this command is destroyed either by the use of the close sub-command or by renaming the command to {}.

The mode string is as per the Tcl open command. If w is specified the file will be created.

ENSEMBLE COMMANDS

$stg opendir name ?mode?: Opens a sub-storage. A new Tcl command is created to manage the resource and the mode is as per the Tcl open command. If 'w' is specified then the sub-storage is created as a child of the current storage if it is not already present. Note: Storages may be read-only or write-only or read-write.

The sub-storage is only usable if all it's parents are still open. This limitation is part of the COM architecture. If a parent storage is closed then the only valid command on its children is a close.
$stg open name ?mode?: Open a file within the storage. This opens the named item and creates a Tcl channel to support reading and writing data. Modes are as per the Tcl 'open' command and may depend upon the mode settings of the owning storage.
$stg close: Closes the storage or sub-storage and deletes the command from the interpreter. See the opendir command for some caveats about this.
$stg stat name varname: Fetches information about an item in the structured storage. This is equivalent to the file stat command and similar fields are set in varname.
$stg commit: Flush changes to the underlying file. At the moment we always use STGM_DIRECT. In the future we may support transacted mode in which case this would do something. However, for multi-megabyte files there is a significant performance hit when using transacted mode - especially during the commit.
$stg rename oldname newname: Change the name of an item
$stg remove name: Removes the item from the storage. If the named item is a sub-storage then it is removed even if not empty.
$stg names: Obtain a list of all item names contained in this storage. The list includes both sub-storage names and stream names and is not sorted.

% package require Storage 1.0.0 % set stg [storage open test.stg w+] stg1 % set stm [$stg open file.txt w] stm1 % puts $stm "Hello, World!" % close $stm % $stg names file.txt % $stg close